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Introductory 


The Installation Guide describes the procedure 
for unpacking, cabling, and powering up a system. 

The Operator's Guide addresses the needs of the 
average user for operating instructions. It 
describes the workstation switches and controls, 
keyboard function, and floppy disk handling. 

The Executive Manual describes the command 
interpreter, the program that first interacts 
with the user when the system is turned on. It 
specifies commands for managing files and 
invoking other programs such as the Editor and 
the programming language compilers. 


Hardware 


The Workstation Hardware Manual describes the 
mainframe, keyboard, and video display. It 
specifies system architecture, printed circuit 
boards (Motherboard, Processor, I / 0-Memory, yideo 
Control, ROM Expansion, and RAM Expansion), 
keyboard, video monitor. Multibus interface, 
communications interfaces, power supply, and 
environmental characteristics of the workstation. 


The AWS-210 Hardware Manual describes the 
mainframe, keyboard, and video display of the 
AWS-210 workstation. It specifies architecture, 
theory of operation of the printed circuit 
boards (Motherboard, Deflection, and CPU), 
keyboard, video monitor, expansion interface, 
communications interface, power supply, and 
environmental characteristics of the workstation. 

The peripherals Hardware Manual describes the 
disk subsystems . It specifies the disk 
controller Motherboard, controller boards for the 
floppy disk and the Winchester disks, power 
supplies, disk drives, and environmental 
characteristics . 


Operating System 

The CTOS" 1 Operating System Man ual describes the 
Operating System. It specifies services for 
managing processes, messages, memory, exchanges, 
tasks, video, disk, keyboard, printer, timer, 
communications, and files. In particular, it 


xxii CTOS" Operating System Manual 



specifies the standard file access methods: SAM, 
the Sequential Access Method; RSAM, the Record 
Sequential Access Method; and DAM, the Direct 
Access Method. 

The System Programmer's Guide addresses the needs 
of the system programmer or system manager for 
detailed information on Operating System 
structure and system operation. It describes (1) 
cluster architecture and operation, (2) 
procedures for building a customized Operating 
System, and (3) diagnostics. 

The System Utilities Manual describes utilities 
such as Backup Volume, IVolume, Restore, Change 
Volume Name, PLog, Maintain File, Dump, etc. 

The Batch Manual describes the batch manager, 
which executes batch jobs under control of job 
control language (JCL) files. 


Programming Languages 

The COBOL , FORTRAN , BASIC , Pascal , and Assembly 
Language Manuals describe the system 1 s 
programming languages. Each manual specifies 
both the language itself and also operating 
instructions for that language. 

71:16 Pascal Manual is supplemented by a popular 
text, Pascal User Manual and Report . 

The Assembly Language Manual is supplemented by a 
text, the Central Processing Unit, which 
describes the main processor, the 8086. It 
specifies the machine architecture, instruction 
set, and programming at the symbolic instruction 
level . 


Program Development Tools 

The Editor Manual describes the text editor. 

The Debugger Manual describes the Debugger, which 
is designed for use at the symbolic instruction 
level. Together with appropriate interlistings, 
it can be used for debugging FORTRAN, Pascal, and 
assembly language programs. (COBOL and BASIC, in 
contrast, are more conveniently debugged using 
special facilities described in their respective 
manuals . ) 
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The Linker/Librarian Manual describes the Linker, 
which links together separately compiled object 
files, and the Librarian, which builds and 
manages libraries of object modules. 


Data Management Facilities 

The ISAM Manual describes the multikey Indexed 
Sequential Access Method. It specifies the 
procedural interfaces and shows how these 
interfaces are called from the various languages. 

The Forms Manual describes the Forms facility 
that includes (l) the Forms Editor, which is used 
to interactively design and edit forms, and (2) 
the Forms run time, which is called from an 
application program to display forms and accept 
user input. 

The Sort/Merge Manual describes (1) the Sort and 
Merge utilities that run as a subsystem invoked 
at the Executive command level, and (2) the 
Sort/Merge object modules that can be called from 
an application program. 


Text Management Facilities 

The Word Processing Manual describes the word 
processor. It specifies the interactive word 
processor and the list processor that merges text 
from records into the blanks of a form document. 

The Font Designer Manual describes the 
interactive utility for designing new fonts 
(character sets) for the video display. 


Communications 


The Asynchronous Terminal Em ulator Manual 

describes the asynchronous terminal emulator. 

The 3270 Terminal Emulator Manual describes the 
3270 emulator package. 

The 2780/3780 RJE Terminal Emulator Manual 
describes the 2780/3780 emulator package. 
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SUMMARY OF CHANGES 


This edition ( A-09-00006-01-D) of the CTOS™ 
Operating System Manual differs from the 

preceding one CA-09-00006-01-C ) as summarized 
below. Some of the enhancements are not 

compatible with previous versions of the 

software . 

The CTOS Operating System (OS) is now available 
in two versions: 

o one version, the compact version, supports 
execution of one application system at a 
time, and 

o the other version supports execution of 
concurrent application systems. 

The compact system, which supports execution of 
application systems one at a time, is similar to 
previous versions of CTOS. It provides all CTOS 
functions except application partition 
management . 


Application Partition Management 

Application partition management enables any 
number of concurrent application systems to be 
executed, each in its own application 
partition. Interactive application systems are 
executed in the primary application partition, 
while noninteractive application systems are 
executed in secondary application partitions. 

The "Overview" and "Concepts" sections, as well 
as the multitasking and other sections, are 
modified to accommodate execution of concurrent 
application systems. The changes include the 
following . 

The new "Application Partition Management" 
section describes the concepts and operations for 
creating and controlling secondary application 
partitions. 

The "Memory Management" section includes the 
memory organization of application partitions for 
both compact systems and systems supporting 
concurrent application systems. 


Summary of Changes 
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The new operation GetUserNumber in the "Process 
Management" section allows a process to determine 
its user number. Each application system has a 
unique user number. 

The concept of exit run files is introduced in 
the "Task Management" section. An exit run file 
is a user-specified file that is loaded and 
activated when an application system exits its 
partition. The two new operations in this 
section are SetExitRunFile , which establishes a 
new exit run file, and QueryExitRunFile , which 
returns the name, password, and priority of an 
exit run file. 

Each application partition has a Variable-Length 
Parameter Block and an Application System Control 
Block (see the "Parameter Management" section), 
as well as other data structures describing the 
application system executing in the partition 
(see Appendix E) . 

The new operation GetpASCB in the "Parameter 
Management" section returns the address of the 
Application System Control Block in an 
application partition. 

System services can now be dynamically installed 
in secondary application partitions, as well as 
in system memory. The part of system memory in 
which system services can be dynamically 
installed is now called extended system 
partitions. See the "System Services Management" 
section . 


Queue Manager 


The queue manager maintains queues for the new 
batch manager (see the Batch Manual ), the printer 
spooler (see the System Utilities Manual ) , and 
other Convergent or user application systems. 
See the new "Queue Management" section. 


Printing 

The printer spooler now provides capabilities not 
previously available. A printer spooler can be 
installed in any cluster workstation, and the 
printers can be reconfigured dynamically. More 
than one printer spooler can serve the same queue 
of print requests. Security is provided by an 
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option that requires a password to be entered 
from the workstation where the printer is located 
before a file is printed. 

The printer spooler is now described in the 
System Utilities Manual . 

The "Printer Spooler Management" section now 
describes only two operations, both new. 
Conf igureSpooler changes the printer spooler 
configuration, and SpoolerPassword sends a file 
password to the printer spooler. 


Local File System 

A cluster workstation with a local file system 
can access files on local mass storage as well as 
files on mass storage at the master 
workstation. The OS can be bootstrapped from a 
cluster workstation's local file system or from 
the master workstation. When bootstrapped from 
the local file system, the cluster workstation is 
immune from system failures at the master 
workstation. See the "File Management" section. 


Workstations 


The AWS family of workstations is now supported, 
consisting of the AWS-210, AWS-220, AWS-230, and 
AWS-240 workstations. 

The IWS family of workstations now includes the 
IWS-110 and IWS-120 workstations. The IWS-120 
workstation was previously called the monitor 
workstation (MWS). 


Additional Changes 

The "File Management" section on the system 
volume includes the following changes: 

o the standard character font CTFont is renamed 
Sys . Font , 

o the Executive and Debugger initialization 
files are now described in the System 
Programmer 1 s Guide , and 
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o 


the $ Directories now expand to a form that 
includes the application system's user number 
rather than the workstation number. 

The "Sequential Access Method" section includes 
the following new features: 

o the x . 25 virtual circuit device, 

configuration file device, and byte stream, 
and 

o three printing modes (normal, image, and 
binary) for printer spooler byte streams, 
which affect the SetlmageMode operation. 

In the "Video Management" section, the Video 
Control Block is expanded. 

In Appendix A, new status codes are added. 

In Appendix B, the standard character set is 
modified. 

In Appendix D, new request codes are added. 

Appendix E is renamed "Data Structures" and now 
includes an expanded System Common Address Table, 
new data structures for application partition and 
batch management, and an expanded System 

Configuration Block (previously Appendix H) . 

Appendix F is now a section named "Conventions 
Used in This Manual" and has been moved to the 
front of the Manual (immediately before 

"Overview" ) . 


xxviii 


CTOS” Operating System Manual 



CONVENTIONS USED IN THIS MANUAL 

Numbers 


Numbers are decimal except When suffixed with "h" 
for hexadecimal. Thus, lOh = 16 and OFFh = 255. 


Memory Address 


Memory address refers to the logical memory 
address. (See the "Memory Management" section.) 


Variable Names 


Variables are named according to a formal 
convention. Some of the characteristics of the 
variable can be inferred from its name. 
Parameters used in procedure definitions and 
fields of request blocks and other data 
structures are named according to this 
convention. 

A variable name is composed of up to three 
parts: a prefix, a root, and a suffix. 


Prefixes 


The prefix identifies the data type of the 
variable. Common prefixes are: 

b byte (8-bit character or unsigned number), 

c count (unsigned number), 

f flag (TRUE = OFFh or FALSE = 0), 

i index (unsigned number), 

n number (unsigned number) (same as "c" ), 

o offset from the segment base address (16 
bits) , 

p logical memory address (pointer) (32 bits 
consisting of the offset and the segment 
base address), 

q quad (32-bit unsigned integer). 
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rg array of , 


s size in bytes (unsigned number), and 

sb array of bytes where first byte is the 
size . 

Prefixes can be composed. Common compound 

prefixes are: 


cb 

count of bytes (the 
string of bytes). 

number 

of bytes in 

pb 

pointer to (logical 
string of bytes, and 

memory 

address of) 

rgb 

array of bytes. 




Roots 


The root of a variable name can be unique to that 
variable, selected from the list below, or a 
compound of the two. Common roots are: 


deb 

Device Control Block, 

ere 

status (error) code. 

exch 

exchange , 

feb 

File Control Block, 

fh 

file handle. 

If a 

logical file address. 

ph 

partition handle 

qeh 

queue entry handle 

rq 

request block, and 

ueb 

User Control Block. 


Suffixes 


The suffix identifies the use of the variable. 
Suffixes are: 

Last the largest allowable index of an array. 


XXX 
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Max the maximum length of an array or buffer 
(thus one greater than the largest 
allowable index), and 

Ret identifies a variable whose value is to 
be set by the called process or procedure 
rather than specified by the calling 
process . 


Examples 

Here are a few examples of variable names: 

cbFileSpec the count of bytes of a file 

specification, 

ercRet the status code to be returned to 

the calling process, 

pbFileSpec the memory address of a string of 
bytes containing a file 

specification, 

pDataRet the memory address of an area into 

which data is to be returned to 

the calling process, 

ppDataRet the memory address of a 4-byte 

memory area into which the memory 
address of a data item is to be 
returned to the calling process, 

pRq the memory address of a request 

block, 

psDataRet the memory address of a (2-byte) 

memory area into which the size of 
a data item is to be returned, 

sData the size (in bytes) of a data 

area , 

sDataMax the maximum size (in bytes) of a 

data area, and 

ssDataRet the size of the area into which 

the size of a data item is to be 
returned . 
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1 OVERVIEW 


The CTOS Operating System, like the Convergent 
Family of Information Processing Systems, was 
developed to meet the broad needs of OEM system 
builders. The underlying concept is foundation 
software : the commitment to support the system 
builder's need to develop a system with its own 
special devices, its own look, its own feel. 


Multiprogramming 


The CTOS Operating System provides a real-time, 
multiprogramming environment. Multiprogramming 
is supported at three levels: application 
systems, tasks, and processes. 

First, any number of application systems can 
coexist, each in its own memory partition. (An 
application system is a collection of one or more 
tasks that access a common set of files and 
implement a single application.) 

Second, any number of tasks can be loaded into 
the memory of a partition and independently 
executed. (A task is an executable program, 
created by translating one or more source 
programs into object modules and linking them 
together . ) 

Third, any number of processes can independently 
execute the code (instructions) of each task. (A 
process is the basic element of computation that 
competes for access to the processor.) 


Event-Driven Priority Scheduling 

To meet the system builder's need for high 
performance, the CTOS Operating System Kernel 
provides efficient, event-driven, priority 
scheduling for an unlimited number of processes. 

Each process is assigned one of 255 priorities 
and is scheduled for execution based on that 
priority. Whenever an event , such as the 
completion of an input/output operation, makes a 
higher priority process eligible for execution, 
rescheduling occurs immediately. This provides a 
more responsive system than scheduling techniques 
that are entirely time based. 
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To give multiple tasks with the same priority a 
fair share of system resources, processes with 
priorities in a predefined range are subject to 
time slicing. Processes with the same priority 
are then executed in turn for intervals of 100 ms 
in round robin fashion. 


Interprocess Communication 

The other major function provided by the CTOS 
Kernel is the interprocess communication (I PC) 
facility. IPC Is used for synchronizing process 
execution and for transmitting information 
between processes. 

A process can send a message and can wait for a 
message. When a process waits for a message, its 
execution is suspended until a message is sent to 
it. This allows processes to synchronize 
execution. A process can also check whether a 
message is available without its execution being 
suspended. 

As a simple example. Process A sends a message to 
Process B and then waits for an answer. Process 
B waits for a message, performs a function 
determined by that message, and then sends an 
answering message. This sequence assures that 
Process B does not begin its function until 
requested and that Process A does not resume 
execution until Process B has completed its 
function . 

As a more complex example. Process A continues 
execution in parallel with the execution of 
Process B before synchronizing execution by 
waiting for the answer. 


Exchanges 


Messages are not sent directly from process to 
process. Rather, they are routed through an 
intermediary element called an exchange . 

Expanding on the example above: Process A sends 
a message to Exchange X and waits at Exchange Y, 
while Process B waits at Exchange X and sends an 
answering message to Exchange Y. 
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A single process can serve several exchanges, in 
which case it can select one of several kinds of 
messages to process next. This can be used to 
set priorities for the work the process is to 
perform. 

Also, several processes can serve the same 
exchange, thereby sharing the processing of a 
single kind of message. 


System Service Processes 

The CTOS Operating System includes a number of 
system service processes . These processes, which 
are scheduled for execution in the same manner as 
application processes, receive IPC messages to 
request the performance of their services. 
Because of this internal use of IPC, the CTOS 
Operating System is classified as message-based . 

Each system service process acts as the guardian 
and manager for a class of system resources such 
as files, memory, or keyboard. Because the 
system service process is the only software 
element that accesses the resource, and because 
the interface to the system service process is 
formalized through the use of IPC, a highly 
modular environment results. 

This modular environment increases reliability by 
localizing the scope of processing and provides 
the flexibility to replace a system service 
process as a complete entity. 

System builders can also include their own system 
service processes, which are then indistinguish- 
able from Convergent ones. 


Accessing System Services 

Each of the functions provided by the system 
service processes can be accessed through the use 
of a procedure call from high-level languages 
such as FORTRAN and Pascal, as well as from 
assembly language. 

The use of a procedural interface masks all the 
complexities of using IPC: the procedural 
interface automatically uses a default response 
exchange and builds the request block message on 
the stack of the calling process. 
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In high-performance applications, however, the 
direct use of IPC operations to access system 
services allows an increased degree of 
concurrency between multiple input /output 
operations and computation. 


Filters 


Requests for system services are directed to the 
appropriate system service process through 
reference to a table that can be modified. This 
allows a system service request to be redirected 
to another system service process and also allows 
the implementation of filters . A filter enables 
the system builder to customize the function of a 
system service without modifying the system 
service process that implements it. 

As an example, a filter process positioned 
between the file management system and its client 
processes can perform special password validation 
before permitting access to a file. 

Local Resource-Sharing Networks (Clusters) 

The CTOS Operating System provides support for 
local resource-sharing networks (clusters), as 
well as for standalone workstations. In a 
cluster configuration (consisting of a master 
workstation and up to 16 cluster workstations), 
essentially the same Operating System executes in 
each cluster workstation as in the master 
workstation. The master workstation provides 
file system and queue management resources for 
all workstations in the cluster. In addition, it 
concurrently supports its own interactive 
application processing. 

In the cluster configuration, the IPC facility is 
extended to provide transparent access to system 
service processes that execute in the master 
workstation. While some services, like file 
management, queue management, 3270 emulator, and 
data base management, migrate to the master 
workstation, others, such as video and keyboard 
management, remain at the cluster workstation. 

One high-speed RS-422 channel is standard on each 
workstation. This channel is used by cluster 
workstations for communication with the master 
workstation. Master workstations of small 
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cluster configurations (up to four cluster 
workstations) use this channel for communications 
with their cluster workstations. However, master 
workstations of large cluster configurations use 
one or two Communications I/O Processors 
(CommlOPs) for communications with their cluster 
workstations . 

The CommlOP , which is added to the Multibus of 
the master workstation, is an intelligent 
communications processor based on the Intel 8085 
microprocessor. The CommlOP serves up to four 
cluster workstations on each of its two high- 
speed serial lines. 


CT-NET Network 


The CT-NET Network extends the CTOS resource- 
sharing capability to permit sharing of file 
system and printer spooler resources between 
clusters connected by leased, voice-grade lines 
and/or an X.25 Value-Added Network. In addition, 
the CT-NET Network permits access to other 
computers through the Value-Added Network. 


Virtual Code Segment Management 

The CTOS virtual code segment management facility 
permits the execution of an application system 
whose size exceeds the available partition 
memory. To ensure maximum real-time performance, 
the use of this facility is under control of the 
system builder; an application system uses 
virtual code segment management only if the 
option is selected when its task image is linked. 

If the virtual code segment facility is selected 
for a task, the code of the task is divided into 
variable-length segments that reside on disk. As 
the task executes, only the code segment being 
executed at a particular time must occupy the 
main memory of the partition. However, to 
maximize performance, recently used code segments 
are retained in memory as long as possible. 
Also, the data of the task remains in the main 
memory of the partition for the duration of task 
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File Management 


The CTOS file management system provides a 
hierarchical organization by volume, directory, 
and file. A volume is automatically recognized 
when placed online. Each file can have a 50- 
character file name, a 12-character password, and 
a file protection level. A file can be 
dynamically expanded or contracted without limit 
as long as it fits on one dish. Concurrent file 
access is controlled by read (shared) and modify 
(exclusive) access modes. 

While providing convenience and security, the 
CTOS file management system supplies the system 
builder with the full throughput capability of 
the disk hardware. This includes reading or 
writing any sector of any open file with one disk 
access, reading or writing up to 65k bytes with 
one disk access, input/output overlapped with 
process execution, and optimized disk arm 
scheduling . 

The duplication of critical volume control 
structures protects the integrity of disk file 
"data against hardware malfunction. The Backup 
Volume utility is able to recover a file if 
either of its redundant File Header Blocks is 
valid . 


Device Handlers 


Accommodation of OEM-written device handlers was 
a major design goal of the CTOS Operating 
System. A device handler can be part of the 
application process or it can be a system service 
process. Its interrupt handler can let the CTOS 
Kernel save process context (in which case it can 
be written in FORTRAN or Pascal), or it can 
receive the interrupt directly from the 
hardware. IPC provides an efficient, yet formal, 
interface from interrupt handler to device 
handler and from device handler to application 
process . 


Other Features 


The CTOS Operating System also provides support 
for video display with multiple split screens, 
unencoded keyboard, communications lines. 
Sequential Access Method, Record Sequential 
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Access Method, Direct Access Method, and Indexed 
Sequential Access Method. 


Command Interpreter 

Interaction with the workstation operator is a 
function of the Convergent Executive, not of the 
CTOS Operating System. This allows the system 
builder to choose the manner in which the video 
display and keyboard are used. 

The Executive is a forms-oriented command 
interpreter providing an operator interface that 
includes a HELP facility, command files, and the 
interactive addition of new commands. The 
Executive is available for program development 
and for system builders that find its operator 
interface compatible with their users' needs. 
However, the Executive is a normal application- 
level program that can easily be replaced by the 
customized command interpreter of the system 
builder. 

See the Executive Manual for more information 
about the Executive . 


Compact System 


A compact version of the CTOS Operating System 
can be created at system build. The compact 
version requires less memory yet provides all 
Operating System functions except the 
simultaneous execution of multiple application 
systems. In the compact version, one application 
system is executed at a time. 


Batch Manager 


Sequential execution of noninteractive applica- 
tion systems is a function of the Convergent 
batch manager. The batch manager interprets job 
control language files that execute specified 
application systems with specified parameters. 
The batch manager is useful for both program 
development and end-user environments. (See the 
Batch Manual for more information about the batch 
manager . ) 
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2 CONCEPTS 


Some of the concepts described in this Section 
are illustrated in program examples in 
Appendix F. Convergent and CTOS conventions, as 
well as the conventions used in this Manual, are 
described in the pages just before Section 1 of 
this Manual. 


STRUCTURE OF THE CTOS OPERATING SYSTEM 

The basic components of the CTOS Operating System 
are : 

o the Kernel, 
o system service processes, 

o system common procedures, 

o object module procedures, and 

o device and interrupt handlers. 

The Kernel, the most primitive yet most powerful 
component of the CTOS Operating System, provides 
process management and interprocess communication 
facilities. It schedules process execution, 
including the saving and restoring of process 
context. A process is the basic element of 

computation that competes for access to the 
processor. The Kernel's interprocess communica- 
tion primitives are the primary building blocks 
for synchronizing process execution and 
transmitting information between processes. 

System service processes are CTOS processes that 
guard and manage system resources. System 
service processes are scheduled for execution in 
the same manner as application processes. 

The four major categories of system services are: 

o task management, 

o file management, 

o device management, and 

o memory management. 
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There are two ways to access CTOS system 
services. The more convenient is by a procedure 
call from a high-level language. The more 
primitive allows an increased degree of 
concurrency between multiple input/output 
operations and computation. 

System common procedures are CTOS procedures that 
perform some common system functions. An example 
of a system common procedure is Exit, which 
terminates the execution of an application 
system. System common procedures are executed in 
the same context and at the same priority as the 
invoicing process. The Video Access Method is an 
example of system common procedures. 

Object module procedures are procedures that are 
supplied as part of an object module file. They 
are not part of the CTOS System Image itself. 
Most application systems require only a subset, 
not a full set, of these procedures. The desired 
subset is linked into the application task. The 
Sequential Access Method is an example of object 
module procedures. 

Device handlers and interrupt handlers of the 
CTOS Operating - System are accessed indirectly 
through the convenient interfaces of the system 
service processes. 

System builders can easily include their own 
system service processes, system common 
procedures, device handlers, and interrupt 
handlers in the CTOS System Image at system 
build. System build is the name for the sequence 
of actions necessary to construct a customized 
CTOS System Image. System build is described in 
the System Programmer 1 s Guide . 
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PROCESSING CONCEPTS 


Under the CTOS Operating System, an application 
system (see Figure 2-1 below) is the collection 
of all logical software elements (tasks) 
currently in a partition. These tasks can be 
loosely or tightly coupled, but all perform 
related portions of the same application. These 
tasks execute asynchronously. 


Program Code 
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Figure 2-1. Relationship of Processes, Tasks, and an Application System. 


A task consists of executable code, data, and one 
or more processes. The code and data can be 
unique to the task or shared with other tasks. A 
task is created by translating one or more source 
programs into object modules and then linking 
them together. This results in a task image that 
is stored on disk in a run file. 
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When requested by a currently active task, such 
as the Convergent Executive, the Operating System 
reads the task image from the run file into 
partition memory, relocates intersegment 
references, and schedules it for execution. The 
new task can coexist with or replace other 
application tasks in its partition memory. 

A process is the basic element of computation 
that competes for access to the processor. A 
process consists of: (1) the address of the next 
instruction to execute on behalf of this process, 
(2) a copy of the data to be loaded into the 
processor registers before control is returned to 
this process, and (3) a stack. A process is 
assigned one of 255 priorities so that the CTOS 
Operating System can schedule its execution 
appropriately . 


CTOS" Operating System Manual 



MEMORY ORGANIZATION 


The memory of a system consists of two types of 
partitions : 

o system partitions, which contain the 
operating system and dynamically installed 
system services, and 

o application partitions, each of which 
contains an application system. 

When a system is initiated, the CTOS Operating 
System is loaded into the system partition at the 
low address end of memory. Dynamically installed 
system services are loaded into extended system 
partitions located at the high address end of 
memory. The remaining memory is defined as a 
single application partition, called the primary 
application partition. (See Figure 2-2.) 
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Figure 2-2. Memory Organization. 
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When new partitions are created, they are placed 
at the high address end of the existing 
application partition and are called secondary 
application partitions. The remaining memory is 
defined as the primary application partition. 
(See Figure 2-3 below.) 




Low End of Memory 

System Partition 


Interactive 

Application -< 

System 


Primary Application Partition 


Noninteractive 
Application -< 

Systems 


Secondary Application Partition B 



Secondary Application Partition A 



Extended System Partition 





Figure 2-3. Memory Organization with Secondary Application Partition. 


The primary application partition is for 
interactive programs that use the keyboard and 
video display to interact with the user. Such 
partitions can be loaded with interactive 
programs chosen by the user, such as the Word 
Processor, a terminal emulator, or a user-written 
application program. 
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Secondary application partitions are for 
noninteractive applications. Such partitions can 
be used for executing batch jobs under control of 
the batch manager, user-written applications, or 
system services. 

A compact version of the Operating System can be 
built at system build that saves on memory yet 
provides all Operating System functions described 
for the execution of one application system at a 
time. The compact version can have only one 
application partition, as shown in Figure 2-2 
above . 


Types of Memory 


Two types of memory allocation are available to 
the application system: long-lived and short- 
lived. Within each application partition, long- 
lived memory expands upward from low memory 
locations while short-lived memory expands 
downward from high memory locations. The CTOS 
Operating System allocates short-lived memory for 
application tasks. 

Processes within an application partition 
allocate and deallocate long-lived and short- 
lived memory by requests to CTOS system 
services. A process in one partition cannot 
allocate or deallocate memory in other 
partitions . 

When the execution of an application system is 
terminated, the short-lived memory of its 
partition is automatically deallocated. 

Long-lived memory is deallocated only at the 
explicit request of the application system. 
Therefore, long-lived memory is useful for 
passing information from an application system to 
a succeeding application system within the same 
partition . 


Concepts 


2-7 



VIRTUAL CODE SEGMENT MANAGEMENT 


Virtual code segment mana gement supports the 
execution of an application system whose size 
exceeds the available memory in its application 
partition. Program code (but not data) can 
reside on disk while a task is executing. Only 
the code segment whose instructions are being 
executed at a particular time need occupy the 
main memory of an application partition. The 

remaining code segments of the application system 
are automatically read into partition memory as 
needed. When necessary, the oldest code segment 
in partition memory is overlaid to make enough 
partition memory available for a new code 
segment . 
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INTERPROCESS COMMUNICATION 


As a message-based operating system, the CTOS OS 
uses its interprocess communication (IPC) 
facility internally For synchronization of 
process execution and information transmission. 
The CTOS Kernel provides IPC primitives to 
facilitate the consistent but flexible exchange 
of information between processes. Processes can 
communicate with each other within or between 
application partitions. 

Six IPC primitives are provided: Check, PSend, 
Request, Respond, Send, and Wait. Both Operating 
System (that is, system service) and application 
system processes use these primitives. 


Messages and Exchanges 

Messages and exchanges are used in IPC. 

A message conveys information and provides 
synchronization between processes. Although only 
a single 4-byte data item is literally 
communicated between processes, this data item is 
usually the memory address of a larger data 
structure. The larger data structure is called 
the message. 

An e xchange is the path over which messages are 
communicated from process to process (or from 
interrupt handler to process) . An exchange 
consists of two first-in, first-out queues: one 
of processes waiting for a message, the other of 
messages for which no process has yet waited. 

Processes or messages (but not both) can be 
queued at an exchange at any given instant. If a 
process waits at an exchange at which messages 
are queued, then the message that was enqueued 
first is dequeued and its address given to the 
process; the process then continues execution. 
Similarly, if a message is sent to an exchange at 
which processes are queued, then the process that 
was enqueued first is dequeued, given the address 
of the message, and placed into the ready state. 

The relationship of exchanges, messages, and 
processes is shown in Figure 2-4 below. 
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Figure 2-4. Relationship of Exchanges, Messages, and Processes. 


Exchanges are allocated in three ways: 


o at system 

processes ) , 

build 

( for 

system 

service 

o dynamically 

using 

the 

AllocExch 

( and 


DeallocExch) operation, and 


o at process creation. 

A process can send a message to a process in 
another application partition. The destination 
process allocates an exchange and makes the 
exchange known to the OS. The sender process 
obtains the exchange number and sends messages to 
the exchange. Each of the processes must lock 
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itself in its partition to prevent interference 
with the communication. 


Process States 


A process can exist in one of three states: 
running, ready, and waiting. 

A process is in the running state when the 
processor is actually executing its 
instructions. Only one process can be in the 
running state at a time. 

A process is in the ready state when it could be 
running, but a higher priority process is 
currently running. Any number of processes can 
be in the ready state at a time. 

A process is in the waiting state when it is 
waiting at an exchange for a message. Any number 
of processes can be waiting at a time. 

Table 2-1 below describes the transitions between 
process states and the events causing the 
transitions. The relationship among process 
states is shown in Figure 2-5 below. 


Table 2-1. Process State Transition. 


Transition 


From 

To 

Event 

Running 

Waiting 

A process executes a 
Wait but no messages 
are at the exchange . 

Waiting 

Ready/ 

Running 

A process sends a 
message to the 
exchange at which a 
process is waiting. 

Running 

Ready 

A higher priority 
process leaves the 
waiting state. 

Ready 

Running 

All higher priority 
processes enter the 
waiting state. 
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Figure 2-5. Process States. 


Process Priorities and Process Scheduling 

Every process has a priority that indicates its 
importance relative to other processes. The 
priority of a process is assigned at process 
creation . 

The CTOS Operating System has event-driven 
priority scheduling . This means that processes 
are scheduled for execution based on their 
priorities and system events, not on a time limit 
imposed by the scheduler. This involves very 
little decision-making for the ,0S. The scheduler 
maintains a queue of the processes that are 
eligible to execute. Priority determines which 
process, among those eligible, is executed. At 
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any time, the OS always allocates the processor 
to the highest priority process that can be 
executed. Rescheduling occurs when a system 
event makes executable a process with a higher 
priority than the one currently executing. 

A system event affects the executability of a 
process. Examples of systerri events are an 
interrupt from a device controller, Multibus 
device, timer, or Real-Time Clock, or a message 
sent from another process. The system event 
causes a message to be sent to an exchange at 
which a higher priority process is waiting; this 
in turn causes the OS to reallocate the 
processor . 

When a system event occurs that makes a process 
eligible to execute, the process receives control 
of the processor until another higher priority 
process preempts its execution, or until it 
voluntarily relinquishes control of the 
processor . 

If no other process has work to perform, the null 
process, which executes at a priority (255) lower 
than any real process and which is always ready 
to run, is given control of the processor. The 
null process exists only to simplify the 
algorithm of the scheduler; it performs no other 
useful work. 

To give multiple tasks with the same priority a 
fair share of system resources, processes with 
priorities in a predefined range are subject to 
time slicing. Such processes with the same 
priority are executed in turn for intervals of 
100 ms in round robin fashion. 


Sending a Message 

When a message is sent to an exchange, the CTOS 
Operating System queues the address of the 
message, not the message itself. Because only 
the address is moved, overhead is minimized, and 
queueing a number of messages at the same 
exchange requires little execution time or 
memory . 
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When a process sends a message to an exchange, 
one of two actions results at the exchange: 

o If no processes are waiting, the message is 

queued . 

o If one or more processes are waiting, the 

process that was enqueued first is given the 

message and is placed into the ready state. 
If this process has a higher priority than 
the sending process, it becomes the running 
process and the sending process loses control 
until it once again becomes the highest 
priority ready process. 

After a message is queued at an exchange, it must 
not be modified by the sending process. A 
process that receives the message by waiting at 
the exchange where the message was queued is free 
to modify the message. 


Waiting for a Message 

When a process waits for a message at an 
exchange, one of two actions results at the 
exchange : 

o If no messages are queued, the process is 
placed into the waiting state until a message 
is sent. When a message is sent, its address 
is returned to the process, which leaves the 
waiting state and is scheduled for execution. 

o If one or more messages are queued, the 
message that was enqueued first is dequeued 
and its address returned to the process, 
which continues to execute. 


Applying Interprocess Communication 

To a large extent, the power of the CTOS 
Operating System results from its interprocess 
communication facility. IPC supports three 

multitasking capabilities: 

o communication, 

o synchronization, and 

o resource management. 
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Communication 


Communication , the most elementary interaction 
between processes, is the transmission of data 
from one process to another via an exchange. 
Figure 2-6 below shows an example of 
communication between Process A and Process B. 
Process A sends a message to Exchange X, and 
Process B waits for a message at that Exchange. 



Figure 2-6. Communication between Processes. 


Synchronization 

Synchronization is the means by which a process 
ensures that a second process has completed a 
particular item of work before the first process 
continues execution. Synchronization between 
processes and the transmission of data between 
processes usually occur simultaneously. 

As shown in Figure 2-7 below, Process A sends a 
message to Exchange Y, requesting that Process B 
perform an item of work. Process A then waits at 
Exchange Z until Process B has completed the 
work. This synchronizes the continued execution 
of Process A with the completion of an item of 
work by Process B. 
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Figure 2-7. Synchronization. 


Resource Management 

In a multitasking environment, resource 
management is the means of sharing resources 
among processes in a controlled way. For 

example, several processes may need to use the 
printer; however, only one process can use the 
printer at a particular time. 
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One way to control a resource is to establish a 
process to manage it. Only the managing process 
accesses the resource directly. Other processes 
access the resource indirectly by sending 
messages to the process that performs the desired 
function. CTOS system services, which manage 
resources such as files, devices, and memory, are 
implemented via an analogous mechanism. 
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CTOS SYSTEM SERVICES 


The CTOS Operating System includes a number of 
system service processes. These processes, which 
are scheduled for execution in the same manner as 
application processes, receive IPC messages to 
request the performance of their services. Any 
process, even a system service process, can use 
(be a client of) a system service process. 

Each system service process acts as the guardian 
and manager for a class of system resources such 
as files, memory, or keyboard. 

CTOS system services can be accessed: 

o indirectly, by a procedural interface, or 

o directly, by the Request and Wait primitives. 

Using the procedural interface is easier because 
it automatically performs most of the necessary 
housekeeping and issues the Request and Wait 
primitives . 

Using the Request and Wait primitives is more 
powerful, however, as it allows a greater degree 
of overlap between multiple input/output 
operations and computation. 


Procedural Access to System Services 

When a procedural interface is used, a request 
block is automatically constructed and the 
default response exchange of the process is 
automatically used. (Request block and default 
response exchange are defined immediately 
below. ) Except for the ReadAsync and WriteAsync 
procedures, the request block is constructed on 
the stack of the client process. 


Direct Access to System Services 

Execution of a system service involves the 
participation of two processes (client and system 
service), three kinds of Kernel primitives 
(Request, Respond, and Wait), two kinds of 
exchanges (response exchange and default response 
exchange), and a data structure (request block). 
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The process requesting the system service is the 
client process. Any process, even a system 
service process, can be a client process, since 
any process can request system services. 

CTOS system services are provided by system 
service processes. These processes are created 
when the system is first loaded and execute code 
that was linked into the System Image at system 
build . 

A request block, a data structure provided by the 
client process, contains the specification of, 
and the parameters to, the desired system 
service. A request block contains a request code 
field, a response exchange field, and several 
other fields. 

A request code is a 16-bit value that uniquely 
identifies the desired system service. For 
example, the request code for the Write operation 
is 36. The request code is used both to route a 
request to the appropriate system service process 
and to specify to that process which of the 
several services it provides is currently 
requested. 

A response exchange is the exchange at which the 
requesting client process waits for the response 
of a system service. The response can be 
directed to the exchange at which the client 
process is expecting it because the exchange at 
which the response is desired is specified in the 
request block. 

A special case of response exchange is the 
default response exchange of a process. Each 
process is given a unique default response 
exchange when it is created. This special 
exchange is automatically used as the response 
exchange whenever a client process uses the 
procedural interface to a system service. 

A service exchange is an exchange that is 
assigned to a system service process at system 
build. The system service process waits for 
requests for its service at its service exchange. 

The Request primitive is a variant of the Send 
primitive. It is used to direct a request for a 
system service from a client process to the 
service exchange of the system service process. 
Request, unlike Send, does not accept an exchange 
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identification as a parameter. Rather, it infers 
the appropriate service exchange by using the 
request code as an index into the Service 
Exchange Table. 

The Service Exchange Table is constructed at 
system build, resides in the System Image, and 
translates request codes to service exchanges. 

The Respond primitive is another variant of the 
Send primitive. System service processes use 
Respond to report the completion of the requested 
system service. 


Interaction of Client Processes and System Service Processes 

The client process initiates the transaction by 
formatting a request block and issuing a Request 
primitive. After issuing the Request primitive, 
the client process can continue execution but 
must not modify the request block. 

In order to determine when the request was 
compfleted, the client process must issue either a 
Wait or a Check primitive. The Wait or Check 
primitive must specify the same exchange that the 
client process specified as the response exchange 
in the request block. 

The Wait primitive suspends execution of the 
client process until the system service process 
responds (or until another message is queued at 
the specified exchange). 

The Check primitive does not suspend execution of 
the client process; instead it inquires whether a 
message is queued at the specified exchange. 

The system service process waits for a request to 
be queued at an exchange. Upon receiving a 
request, the system service process verifies the 
control information and data given it before 
processing the request. After performing the 
requested function, it acknowledges completion of 
the service by responding to the client process. 
It then resumes waiting until it receives the 
next request. 

The interaction of client and system service 
processes is shown in Figure 2-8 below. The 
processing flow of client and system service 
processes is shown in Figure 2-9 below. 
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Figure 2-8. Interaction of Client and System Service Processes. 


Filter Processes 


A filter process is a user-written system service 
process that is included in the System Image at 
system build. A filter process is interposed 
between a client process and a system service 
process that believe they are communicating 
directly with each other. The Service Exchange 
Table is adjusted at system build to route 
requests through the desired filter process. 

A filter process might be used between the file 
management system and its client process to 
perform special password validation on all or 
some requests. 
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Compute 
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Figure 2-9. Processing Flow of Client and System Service Processes. 


The interaction of a filter process with a client 
process and system service process is shown in 
Figure 2-10 below. 

Request Blocks 

The format of request blocks is designed to allow 
the transparent migration of system service 
processes between standalone and cluster 
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configurations. Request blocks are completely 
self-describing and consist of four parts: 

1. a standard header, 

2. request-specific control information, 

3. descriptions of the request data items, and 

4. descriptions of the response data items. 

Each data item is described by memory address, 
size, and source (client or system service 
process) . 



Figure 2-10. Interaction of Filter Process with Client and System Service Processes. 
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CLUSTER CONFIGURATION 


Cluster configurat io ns of the Convergent Family 
of Information Processing Systems consist of a 
master workstation and up to 16 cluster 
workstations (CWS). Essentially the same 
Operating System executes in each CWS as in the 
master workstation. The master workstation 
provides file system and queue management 
resources for all workstations in the cluster . 
In addition, it concurrently supports its own 
interactive application processing as well as 
user-written multiuser system services. A CWS 
can have its own local file system and printer 
spooler . 

In the cluster configuration, the IPC facility is 
extended to provide transparent access to system 
service processes that execute in the master 
workstation. While some services, like file 
management, queue management, 3270 terminal 
emulator, and data base management, migrate to 
the master workstation, others, such as video and 
keyboard management, remain at the CWS. 

Application systems access the file system of a 
master workstation exactly as they do that of a 
standalone workstation. A program that works on 
a standalone workstation (accessing the local 
file system) can be moved to a CWS (accessing the 
file system of the master workstation) without 
modification, recompilation, or relinking. 


Interstation Communication 

The interstation communication (ISC) facility is 
an upward-compatible extension of the 
interprocess communication facility. When a 
client process requests a system service, a 
request block is constructed that contains all 
the information necessary to describe the desired 
function . 

In a standalone workstation, the request block is 
queued at the exchange of the system service 
process that actually performs the desired 
function. 
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CWS Agent Service Process 


In a CWS, however, if the function is to be 
performed at the master workstation, then the 
request block is queued at the exchange of the 
CWS Agent Service Process. The CWS Agent Service 
' Process converts interprocess requests to 
interstation messages for transmission to the 
master workstation. The CWS Agent Service 
Process is included at system build in a System 
Image that is to be used on a CWS. 


Master Workstation Agent Service Process 

The System Image used at the master workstation 
is built to include a corresponding service 
process. This process, the master workstation 
Agent Service Process , reconverts the 
interstation message to an interprocess request 
that it queues at the exchange of the master 
workstation system service process that actually 
performs the desired function. Note that the 
Service Exchange Table that translates the 
request code to a service exchange at the master 
workstation is necessarily different from the 
table at the CWS. 

When the system service process at the master 
workstation responds, the response is routed 
through the master workstation Agent Service 
Process, the high-speed data link, and the CWS 
Agent Service Process before being queued at the 
response exchange in the CWS that was specified 
in the request block. 

The format of request blocks is designed to allow 
the CWS and master workstation Agent Service 
Processes to convert between interprocess 
requests and interstation messages efficiently 
and with no external information. Because 
request blocks are completely self-describing, 
the Agent Service Processes can transfer requests 
and responses between master workstation and CWSs 
without any knowledge of what function is 
requested or how it is to be performed. 


Interstation Request/Response Messages 

An interstation request message consists of: 
o a header, 
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o control information, 

o the. size and actual text of each request data 
item, and 

o the maximum allowed size of each response 

data item. 

An interstation response message consists of: 
o a status code, and 

o the actual size and text of each response 

data item. 

The CWS Agent Service Process forms an 
interstation request message by copying the 
header and control information from the request 
block, moving the actual text of the request data 
items into the message, and including a 

specification of the maximum allowed sizes of the 
response data items. 

After receiving the interstation response 

message, the CWS Agent Service Process stores the 
status code into the request block and moves the 
text of the response data items into the memory 
areas specified for them by the request block. 
This transformation scheme ensures that no 
redundant or extraneous information is 

transmitted between master workstation and CWSs. 


Communications I/O Processor 

One high-speed RS-422 channel is standard on each 
workstation. This channel is used by cluster 
workstations for communications with the master 
workstation. Master workstations of small 
cluster configurations (up to four cluster 
workstations) use this channel for communications 
with their cluster workstations. Master 
workstations of large cluster configurations use 
one or two Communications I/O Processors 
(CommlOPs) for communications with their cluster 
workstations . 

The CommlOP , which is added to the Multibus of 
the master workstation, is an intelligent 
communications processor based on the Intel 8085 
microprocessor. The CommlOP serves up to four 
cluster workstations on each of its two high- 
speed serial lines. 
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ComralOP software consists of an 8085 bootstrap- 
ROM program, the main CommlOP program (which 
executes in 8085 RAM), and a CommlOP handler 
(written in 8086 code) which executes in system 
memory under CTOS control. 


Software Organization 

A CTOS System Image built for a CWS differs from 
a CTOS System Image built for a standalone 
workstation in the (optional) exclusion of the 
file management system and the disk handler, and 
the inclusion of the CWS Agent Service Process. 

A CTOS System Image built for a master 
workstation differs from a CTOS System Image 
built for a standalone workstation only in its 
inclusion of the master workstation Agent Service 
Process. The master workstation is the file 
server for the entire cluster configuration. 
However, this does not necessitate the use of a 
different file management system from the one 
used in the standalone workstations. In fact, 
the file management system of the CTOS Operating 
System is actually a multiuser file system, even 
in a standalone workstation. 


User-Written Software in a Cluster Configuration 

Concurrency is the major issue concerning 
application systems executing on CWSs. Preferred 
programming practice dictates that the client 
process of a system service always examines the 
status code returned by the system service. 
However, while a program that opens a file 
without considering the possibility of receiving 
status code 220 (“File in use") executes 
successfully on a standalone workstation, such a 
program fails intermittently when executed on a 
CWS at the same time that a program in another 
workstation is modifying the same file. 

Whether user-written system services are good 
candidates for supporting multiple client 
processes depends on both the function they 
perform and the generality with which they are 
written. As an example, consider a user-written 
handler for a special Multibus device. If it 
used the standard format for request blocks, the 
device handler could be relocated to the master 
workstation. However, if it did not include 
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concurrency checks, the device handler might 
become confused when it received requests from 
two or more workstations. 


CT-NET 

(To be supplied) 
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3 PROCESS MANAGEMENT 


OVERVIEW 


Th e process management facility provides event- 
driven priority scheduling and dynamic creation 
of multiprocess tasks. 

Within each task of the application system and 
within the OS itself, the basic element of 
computation that competes for access to the 
processor is a process . Every process is 
assigned a priority. At all times, the CTOS 
process management facility allocates the 

processor to the highest priority process 
currently requesting it. 
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CONCEPTS 

Process 

A process is the basic element of computation 
that competes for access to the processor and 
which the CTOS OS schedules for execution. 

A task has a single process associated with it 
when it is first loaded. That single process can 
create additional processes using the 
CreateProcess operation. The additional 
processes created typically share the same code 
but have separate stacks. The degree and means 
of data sharing are application-specific. 

Processes and tasks usually have a hierarchical 
relationship. However, processes can execute 
code in multiple tasks. The usual relationship 
of a process to the tasks of an application 
system is shown in Figure 3-1 below. 


Context of a Process 

The context of a pr ocess is the collection of all 
information about a process. The context has 
both hardware and software components. 

The hardware context of a process consists of 
values to be loaded into processor registers when 
the process is scheduled for execution. This 
includes the registers that control the location 
of the process's stack. 

The software context of a process consists of its 
default response exchange and the priority at 
which it is to be scheduled for execution. 

The combined hardware and software context of a 
process is maintained in a system data structure 
called a Process Control Block (PCB). A PCB is 
the physical representation of a process. 

When a higher priority process preempts a lower 
priority process, the OS saves the hardware 
context of the preempted process in that 
process's PCB. The OS later restores the 
contents of the registers when the process is 
rescheduled for execution; this permits the 
process to continue as though it were never 
interrupted. This is known as a context switch . 
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Figure 3-1. Relationship of Processes, Tasks, and an Application System. 


Process Priorities and Process Scheduling 

Every process has a priority that indicates its 
importance relative to other processes. The 
priority of a process is assigned at process 
creation. Priorities range from 0 to 254 with 0 
being the highest priority. 

The OS has event -driven priority scheduling. 
This means that processes are scheduled for 
execution based on their priorities and system 
events, not on a time limit imposed by the 
scheduler. This involves very little decision- 
making for the OS. The scheduler maintains a 
queue of the processes that are eligible to 
execute. Priority determines which process among 
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those eligible is executed. At any time, the OS 
always allocates the processor to the highest 
priority process that can be executed. 

Rescheduling occurs when a system event makes 
executable a process with a higher priority than 
the one currently executing. In most cases, the 
interval between events is determined by the 
duration of the typical input/output operation. 
A process never loses control involuntarily to 
another process of equal priority, only to a 
process of higher priority. 

A system event affects the executability of a 
process. Examples of system events are an 
interrupt from a device controller. Multibus 
device, timer, or Real-Time Clock, or a message 
sent from another process. The system event 
causes a message to be sent to an exchange at 
which a higher priority process is waiting; this 
in turn causes the OS to reallocate the 
processor . 

When a system event occurs that makes a process 
eligible to execute, the process receives control 
of the processor until another higher priority 
process preempts its execution, or until it 
voluntarily relinquishes control of the 
processor . 

If no other process has work to perform, the null 
process, which executes at a priority (255) lower 
than any real process and which is always ready- 
to-run, is given control of the processor. The 
null process exists only to simplify the 
algorithm of the CTOS scheduler; it performs no 
other useful work. 

To give multiple tasks with the same priority a 
fair share of system resources, processes with 
priorities in a predefined range are subject to 
time slicing. Such processes with the same 
priority are executed in turn for intervals of 
100 ms in round robin fashion. The priority 
range is a system build parameter, the default of 
which is 128 (80h) to 254 (FEh) . 


Process States 

A process can exist in one of three states: 
running, ready, and waiting. 
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The relationship among process states is shown in 
Figure 3-2 below. 

A process is in the running state when the 
processor is actually executing its 
instructions. Only one process can be in the 
running state at a time. Any other ready-to-run 
processes are in the ready state. As soon as the 
running process waits, the highest priority 
process in the ready state is placed into the 
running state and the execution context is 
switched to that process's context. 



A process is in the ready state when it could be 
running, but a higher priority process is 
currently running. Any number of processes can 
be in the ready state at a time. 
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A process is in the waiting state when it is 
waiting at an exchange for a message. A process 
enters the waiting state when it must synchronize 
with other processes. A process can only enter 
the waiting state by voluntarily issuing a Wait 
primitive that specifies an exchange at which no 
messages are currently queued. The process 
remains in the waiting state until another 
process (or interrupt handler) issues a Send (or 
PSend, Request, or Respond) primitive that 
specifies (indirectly in the case of 
Request/Respond) the same exchange that was 
specified by the Wait primitive. Any number of 
processes can be waiting at a time. (See the 
"Interprocess Communication Management" section 
for more information on the Wait, Send, PSend, 
Request, and Respond primitives.) 


Table 3-1 below describes the transitions between 
process states and the events causing the 
transitions . 


Table 3-1. Process State Transition. 

Transition 

From 

To 

Event 

Running 

Waiting 

A process executes a 
Wait but no messages 
are at the exchange. 

Waiting 

Ready/ 

Running 

Another process 
sends a message to 
the exchange at 
which a process is 
waiting . 

Running 

Ready 

A higher priority 
process leaves the 
waiting state. 

Ready 

Running 

All higher priority 
processes enter the 
waiting state. 
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OPERATIONS: PRIMITIVES AND PROCEDURES 


Process management provides the operations listed 
below . 

ChangePriority changes the priority of the 

calling process. 

CreateProcess creates a new process and 

schedules it for execution. 

GetUserNumber allows a process to determine 

its own user number. 

QueryProcessNumber 

allows a process to determine 
its own process number. 
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ChangePriority 

Description 

The ChangePriority primitive changes the priority 
of the calling process. 

Procedural Interface 

ChangePriority (priority) : ErcType 

where 

priority is the new priority. 

Request Block 

ChangePriority is a Kernel primitive. 
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CreateProcess 


Description 

The CreateProcess primitive creates a new process 
and schedules it for execution. CreateProcess is 
called by an application process to establish an 
application system in which multiple processes 
execute the same reentrant task code. 

The CreateProcess primitive is also used by the 
Chain and LoadTask operations to create the 
initial process of a new task. (See the "Task 
Management" section.) 

Procedural Interface 

CreateProcess (pProcessDescriptor ) : ErcType 
where 

pProcessDescriptor 

is the memory address of a Process 
Descriptor Block. The format for a 
Process Descriptor Block is shown in 
Table 3-2 below. 


Request Block 


CreateProcess is a Kernel primitive. 
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Table 3-2. 

Process Descriptor Block. (Page 1 of 2) 

Offset 

Size 

(bytes) 

Field 

Description 

0 

4 

pEntry 

Memory address (CS:IP) at 
which to begin execution 
of the new process. 

4 

2 

saData 

Segment base address to be 
loaded into the Data 
Segment (DS) register when 
the new process is sched- 
uled for execution. 

6 

2 

saExtra 

Segment base address to be 
loaded into the Extra 
Segment (ES) register when 
the new process is sched- 
uled for execution. 

8 

2 

saStack 

Segment base address to be 
loaded into the Stack 
Segment (SS) register when 
the new process is sched- 
uled for execution. 

10 

2 

oStacklnit 

Offset value to be loaded 
into the Stack Pointer 
(SP) register when the new 
process is scheduled for 
execution . 

12 

1 

priority 

Priority (0-254, with 0 the 
highest) at which the new 
process is to be scheduled 
for execution. 
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Table 3-2. Process Descriptor Block. (Page 2 of 2) 


Size 

Offset (bytes) Field Description 

13 1 fSys Always FALSE. A value of 

TRUE would indicate that 
the new process was a 
system process and would 
cause a subsequent Chain 
operation to fail . 

14 2 defaultResponseExchange 

Identification of an 
exchange that the calling 
process has allocated 
using the AllocExch 
operation. (See the 
"Exchange Management" 
section.) This exchange 
becomes the default 
response exchange of the 
new process. The calling 
process must never use 
this exchange again in 
order to avoid possible 
conflict . 


16 1 fDebug Indicates whether the new 

process is to be 
debugged. TRUE indicates 
it will be debugged, and, 
therefore, is not to be 
scheduled for execution; 
FALSE indicates it is to 
be scheduled for execu- 
tion. (See the Debugger 
Manual . ) 
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Ge tUs e r Nuiribe r 


Description 


The GetUserNumber procedure allows a process to 
determine its own user number. 

Procedural Interface 

GetUserNumber (pUserNumberRet) : ErcType 

where 

pUserNumberRet 

is the memory address of a word into 
which the user number of the 
inquiring process is returned. 


Request Block 


GetUserNumber is a system common procedure. 
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QueryProcessNumber 

Description 

The QueryProcessNumber procedure allows a process 
to determine its own process number. 

Procedural Interface 

QueryProcessNumber (pProcessNumberRet) : ErcType 
where 

pProcessNumberRet 

is the memory address of a word into 
which the process number of the 
inquiring process is returned. 

Request Block 

QueryProcessNumber is a system common procedure. 
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4 INTERPROCESS COMMUNICATION MANAGEMENT 


OVERVIEW 


The interprocess communication (IPC) facility 
synchronizes process execution and information 
transmission between processes through the use of 
messages and exchanges. A process can 
communicate with another process in its own 
partition or in another application partition. 


Messages 


A process can send a message and wait for a 
message. When a process waits for a message, its 
execution is suspended until a message is sent to 
it. This allows processes to synchronize 
execution. A process can also check whether a 
message is available without its execution being 
suspended . 

In its simplest form, IPC provides unidirectional 
transmission of arbitrary data. After preparing 
a data structure (a message) that is to be passed 
to another process, Process A uses the IPC 
facility to send the address of the message to 
Process B. Only the address of the message, not 
the message itself, is buffered by IPC. The size 
and content of the message are not constrained by 
IPC. Process B must be programmed to use the IPC 
facility to wait or check for the availability of 
a message. 

The full power of IPC is best appreciated when 
pairs of unidirectional transmissions are 
matched . 

As a simple example. Process A sends a message to 
Process B and then waits for an answer. Process 
B waits for a message, performs a function 
determined by that message, and then sends an 
answering message. This sequence assures that 
Process B does not begin its function until 
requested and that Process A does not resume 
execution until Process B has completed its 
function . 

Since Process B does not send an answer until 
after it has processed the message, the answer 
can signal Process A that the message is no 


IPC Management 


4-1 



longer being used by Process B and (possibly) 
that Process B has modified the message in a 
manner agreed upon by the two processes. 

As a more complex example. Process A continues 
execution in parallel with the execution of 
Process B before synchronizing execution by 
waiting for the answer. 


Exchanges 


A message is sent to a system entity called an 
exchange rather than directly to a process. An 
exchange should be thought of as serving the 
function of a post office where postal patrons 
(processes) go to mail (send) letters (messages) 
or pick up (wait/check for) letters (messages). 

In the same way that a postal patron drops a 
letter in the mailbox and then walks away 
trusting that the letter will be delivered, a 
process sends a message and then continues 
executing without further regard for the message. 

A postal patron who is expecting an important 
letter can periodically go to the post office to 
check whether it has arrived. If the letter is 
especially important, the patron can wait in the 
post office for the letter to arrive. 

A process has analogous mechanisms available when 
it expects to receive a message. It can 

periodically check whether a message is posted at 
(enqueued on) an exchange, or it can wait at the 
exchange for the arrival of a message. Because 
computers are many orders of magnitude faster 
than the postal service, it is usually more 
appropriate to wait for a message than to check 
for its arrival . 

A process can send a message to a process in 

another application partition. The destination 
process allocates an exchange, then makes the 
exchange known to the Operating System. The 

sender process obtains the exchange number and 

sends messages to the exchange. Each process 

must lock itself into its partition so it cannot 
be terminated. 
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System Service Processes 


The CTOS Operating System includes a number of 
system service processes. These processes, which 
are scheduled for execution in the same manner as 
application processes, receive IPC messages to 
request the performance of their services. Any 
process, even a system service process, can use 
(be a client of) a system service process. 

Each system service process acts as the guardian 
and manager for a class of system resources such 
as files, memory, or keyboard. Because the 
system service process is the only software 
element that accesses the resource, and because 
the interface to the system service process is 
formalized through the use of IPC, a highly 
modular environment results. 

This modular environment increases reliability by 
localizing the scope of processing and provides 
the flexibility to replace a system service 
process as a complete entity. 

System builders can also include their own system 
service processes, which are then indistinguish- 
able from Convergent ones. 


Accessing System Services 

CTOS system services can be accessed: 

o indirectly, by a procedural interface, or 

o directly, by the Request and Wait primitives. 

Using the procedural interface is easier because 
it automatically performs most of the necessary 
housekeeping, as well as issues the Request and 
Wait primitives. 

Using the Request and Wait primitives is more 
powerful, however, as it allows a greater degree 
of overlap between multiple input/output 
operations and computation. 

When the processes of an application system use 
the Send and Wait primitives to communicate among 
themselves, they are free to structure their 
messages in whatever way is most convenient. 
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They are also free to pair unidirectional 
transmissions into bidirectional transmissions 
using whatever conventions are convenient or to 
use the IPC facility in a manner that does not 
involve pairing. 

When communicating with CTOS system service 
processes, however, the rules are different. The 
concept of pairing two unidirectional 
transmissions into a bidirectional transmission 
is formalized and enforced. Also, the format of 
the message that is communicated is formalized. 

The format of the message (a request block) is 
designed to allow the transparent migration of 
system service processes between standalone and 
cluster configurations. Request blocks are 

completely self-describing and consist of (1) a 
standard header, (2) request-specific control 
information, and (3) descriptions of the request 
and response data items. Each data item is 
described by memory address, size, and source 
(client or system service process) . 

The Send primitive is not used to communicate 
with CTOS system services. Rather, two other 
primitives. Request and Respond, initiate the 
request for a system service and its response. 
This provides : 

o assurance that Requests and Responds are 

matched, 

o assurance that system resources are always 

available to transmit responses, 

o opportunity to redirect requests for system 

services to other system service processes, 
and 

o opportunity to redirect requests for system 

services to the master workstation of a 
cluster configuration. 


Filter Processes 


Requests for system services are directed to the 
appropriate system service process through 
reference to a table that can be modified. This 
allows a system service request to be redirected 
to another system service process and also allows 
the implementation of filters. A filter enables 
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the system builder to customize the function of a 
system service without modifying or even looking 
at the system service process that implements it. 

As an example, a filter process positioned 
between the file management system and its client 
process can perform special password validation 
before permitting access to a file. 


Cluster Configuration 

In the cluster configuration, the IPC facility is 
extended to provide transparent access to system 
service processes that execute in the master 
workstation. In the master workstation, the CTOS 
Operating System concurrently supports local 
application processing and resource sharing (disk 
and printer) for the other workstations of the 
cluster. While some services, like file 
management, queue management, 3270 terminal 
emulator, and data base management migrate to the 
master workstation, others, such as video and 
keyboard management, remain at the cluster 
workstation . 
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CONCEPTS 


Th e interprocess communication (IPC) facility 
provides process synchronization and information 
transmission through the use of messages and 
exchanges . 


Messages 

A message conveys information and provides 
synchronization between processes. Although only 
a single 4-byte data item is literally 
communicated between processes, this data item is 
usually the memory address of a larger data 
structure. The larger data structure is called 
the message, while the 4-byte data item is 
conventionally called the address of the 
message. The message can be In any part of 
memory that is under the control of the sending 
process. By convention, control of the memory 
that contains the message is passed along with 
the message. 


Exchanges 


An exchange is the path over which messages are 
communicated from process to process (or from 
interrupt handler to process) . An exchange 
consists of two first-in, first-out queues: one 
of processes waiting for a message, the other of 
messages for which no process has yet waited. An 
exchange is referred to by a unique 16-bit 
integer . 

Processes o£ messages (but not both) can be 
queued at an exchange at any given instant. If a 
process waits at an exchange at which messages 
are queued, then the message that was enqueued 
first is dequeued and its memory address given to 
the process; the process then continues 
execution. Similarly, if a message is sent to an 
exchange at which processes are queued, then the 
process that was enqueued first is dequeued, 
given the address of the message, and placed into 
the ready state. 
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structures ( link blocks ) are 
messages onto an exchange, 
ontains the address of the 
Iress of the next link block 
linked onto the exchange, 
leued onto an exchange by 
ield of each Process Control 
ed for this purpose. 

f exchanges, messages, and 
n Figure 4-1 below. 




Exchange Allocation 


Exchanges are allocated in three ways: 

o Exchanges for system service processes are 

allocated at system build. 

o Exchanges can be dynamically allocated and 

deallocated using the AllocExch and 
DeallocExch operations. (See the "Exchange 
Management" section. ) 

o When a process is created, its creator gives 
it a unique default response exchange. A 
process can determine the identification of 
its own default response exchange using the 
QueryDefaultRespExch operation. (See the 

"Exchange Management" section.) 


Sending a Message 

When a message is sent to an exchange, the OS 
queues the address of the message at the 
exchange. Thus overhead is minimized, since just 
the address of the message, not the message 
itself, is moved. Therefore queueing a number of 
messages at the same exchange requires very 
little execution time or memory. 

When a process sends a message to an exchange, 
one of two actions results at the exchange: 

o If no processes are waiting, the message is 
queued . 

o If one or more processes are waiting, the 
process that was enqueued first is given the 
message and is placed in the ready state. If 
this process has a higher priority than the 
sending process, it becomes the running 
process and the sending process loses control 
until it once again becomes the ready process 
with the highest priority. 

After a message is queued at an exchange, it must 
not be modified by the sending process. A 
process that receives the message by waiting at 
the exchange where the message was queued is free 
to modify the message. 
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The Send primitive transfers a 4-byte field from 
the sending process to the waiting process. The 
4-byte field can be interpreted as the memory 
address of a data structure but this is not 
necessary. The interpretation of the 4-byte 
field is by agreement of the two processes 
involved . 


Waiting for a Message 


When a 

process waits 

for a 

message 

at an 

exchange , 
exchange : 

one of two 

actions 

results 

at the 

o If no messages are 

queued , 

the process is 


placed in the waiting state until a message 
is sent. When a message is sent, its memory 
address is returned to the process, which 
leaves the waiting state and is scheduled for 
execution. 

o If one or more messages are queued, then the 
message that was enqueued first is dequeued 
and its memory address returned to the 
process, which continues to execute. 


Sending Messages to Another Partition 

A process can send a message to a process in 
another application partition (interpartition 
communication) . The destination process first 
allocates an exchange with the AllocExch 
operation, then uses the SetPartitionExchange 
operation to make the exchange known to the OS. 
The sender process uses the GetPartitionExchange 
operation to obtain the exchange number, then 
sends messages to the exchange. 

Each process must use the LockPartition operation 
to lock itself into its partition so that it 
cannot be terminated by a TerminatePartitionTasks 
or VacatePartition operation. 

The AllocExchange operation is described in the 
"Exchange Management" section. The GetPartition- 
Exchange, LockPartition, SetPartitionExchange, 
TerminatePartitionTasks, and VacatePartition 
operations are described in the "Application 
Partition Management" section. 
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System Service Processes 


The CTOS Operating System includes a number of 
system service proce sses . These processes, which 
are scheduled for execution in the same manner as 
application processes, receive IPC messages to 
request the performance of their services. Any 
process, even a system service process, can use 
(be a client of) a system service process. 

Each system service process acts as the guardian 
and manager for a class of system resources such 
as files, memory, or keyboard. Because the 
system service process is the only software 
element that accesses the resource, and because 
the interface to the system service process is 
formalized through the use of IPC, a highly 
modular environment results. 

This modular environment increases reliability by 
localizing the scope of processing and provides 
the flexibility to replace a system service 
process as a complete entity. 

System builders can also include their own system 
service processes, which are then 
indistinguishable from Convergent ones. 


Accessing System Services 

CTOS system services can be accessed: 

o indirectly, by a procedural interface, or 

o directly, by the Request and Wait primitives. 

Using the procedural interface is easier because 
it automatically performs most of the necessary 
housekeeping, as well as issues the Request and 
Wait primitives. 

Using the Request and Wait primitives is more 
powerful, however, as it allows a greater degree 
of overlap between multiple input/output 
operations and computation. 


Procedural Access to System Services 

When a procedural interface is used, a request 
block is automatically constructed and the 
default response exchange of the process is 
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automatically used. Except for the ReadAsync and 
WriteAsync procedures, the request block is 
constructed on the stack of the client process. 

Most procedural interfaces to system services do 
not provide any overlap between computation by 
the client process and execution of the system 
service. Because Read and Write are the system 
services for which the overlap of computation and 
execution of the system service is most 
desirable, Convergent has provided the procedures 
ReadAsync and CheckReadAsync and WriteAsync and 
CheckWriteAsync . (See the "File," "Disk," and 
"Printer Spooler Management" sections.) These 
procedures allow the client process to initiate 
an input /output operation and then compute and/or 
initiate other input/output operations before 
checking for the successful completion of the 
input/output operation. 


Direct Access to System Services 

Execution of a system service involves the 
participation of two processes (client and system 
service), three kinds of Kernel primitives 
(Request, Respond, and Wait), two kinds of 
exchanges (response exchange and default response 
exchange), and a data structure (request block). 

The process requesting the system service is the 
client process . Any process, even a system 
service process, can be a client process, since 
any process can request system services. 

CTOS system services are provided by system 
service processes . These processes are created 
when the system is first loaded and execute code 
that was linked into the System Image at system 
build . 

System services are customized at system build 
through the inclusion/exclusion of Convergent- 
written system service processes in the System 
Image. User-written system service processes can 
also be included, either to replace or to augment 
the Convergent-written ones. User-written system 
service processes have the same power and 
flexibility as Convergent-written ones; 
customizing the set of system services requires 
no modification to Convergent-written code. 
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A request block , a data structure provided by the 
client process, contains the specification and 
the parameters of the desired system service. A 
request block contains a request code field, a 
response exchange field, and several other fields 
that are explained in the section below on 
"Request Blocks." 

A request code is a 16-bit value that uniquely 
identifies the desired system service. For 
example, the request code for the Write operation 
is 36. The request code is used both to route a 
request to the appropriate system service process 
and to specify to that process which of the 
several services it provides is currently 
requested . 

A response exchange is the exchange at which the 
requesting client process waits for the response 
of a system service. The response can be 
directed to the exchange at which the client 
process is expecting it because the exchange at 
which the response is desired is specified in the 
request block. 

A special case of response exchange is the 
default response exchange of a process. Each 
process is given a unique default response 
exchange when it is created. This special 
exchange is automatically used as the response 
exchange whenever a client process uses the 
procedural interface to a system service. 

For this reason, the direct use of the default 
response exchange is not recommended. The use of 
the default response exchange is limited to 
requests of a synchronous nature. That is, the 
client process, after specifying the exchange in 
a Request, must wait for a response before 
specifying it again (indirectly or directly) in 
another Request. 

A service exchange is an exchange that is 
assigned to a system service process at system 
build. The system service process waits for 
requests for its services at its service 
exchange . 

The Request primitive is a variant of the Send 
primitive. It is used to direct a request for a 
system service from a client process to the 
service exchange of the system service process. 
Request, unlike Send, does not accept an exchange 
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identification as a parameter. Rather, it infers 
the appropriate service exchange by using the 
request code as an index into the Service 
Exchange Table. 

The Service Exchange Table is constructed at 
system build, resides in the System Image, and 
translates request codes to service exchanges. A 
companion table, the Local Service Code Table , 
translates each request code to a local service 
code to specify which of the several services of 
the system service process is desired. 

The Respond primitive is another variant of the 
Send primitive. System service processes use 
Respond to report the completion of the requested 
system service. The exchange to which the 
response is directed is not a direct parameter to 
Respond but is obtained from the response 
exchange field of the request block. Only system 
service processes are allowed to use the Respond 
primitive, and they must always specify as a 
parameter the same request block that the client 
process used to request the system service. 


Interaction of Client Processes and System Service Processes 

The client process initiates the transaction by 
formatting a request block and issuing a Request 
primitive. The client process can then continue 
execution but must not modify the request 
block. In order to determine when the request 
was completed, the client process must issue 
either a Wait or a Check primitive. The Wait or 
Check primitive must specify the same exchange 
that the client process specified as the response 
exchange in the request block. 

The Wait primitive suspends execution of the 
client process until the system service process 
responds (or until another message is queued at 
the specified exchange). 

The Check primitive does not suspend execution of 
the client process; instead it inquires whether a 
message is queued at the specified exchange. 

The system service process waits for a request to 
be queued at an exchange. Upon receiving a 
request, the system service process verifies the 
control information and data given it before 
processing the request. 
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If the request is invalid, the system service 
process inserts an appropriate error code into 
the status code field (that is, ercRet) of the 
request block. 

If the request is valid, the system service 

process performs the request, places appropriate 
information into the response packets described 
by the request block, inserts a normal status 
code into the request block, and acknowledges 
completion of the service by responding to the 
exchange specified by the client process. It 
then resumes waiting until it receives the next 
request . 

The interaction of client and system service 

processes is shown in Figure 4-2 below. 



Figure 4-2. interaction of Client and System Service Processes. 
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The processing flow of client and system service 
processes is shown in Figure 4-3 below. 



Figure 4-3. Processing Flow of Client and System Service Processes. 


Filter Processes 

A f ilter process is a user-written system service 
process that is included in the System Image at 
system build. A filter process is interposed 
between a client process and a system service 
process that believe they are communicating 
directly with each other. The Service Exchange 
Table is adjusted at system build to route 
requests through the desired filter process. 
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A filter process might be used between the file 
management system and its client process to 
perform special password validation on all or 
some requests. 

The interaction of a filter process with a client 
and system service process is shown in Figure 4-4 
below. 



Figure 4-4. Interaction of Filter Process with Client and System Service Processes. 


Request Blocks 


The format of request blocks is designed to allow 
the transparent migration of system service 
processes between standalone and cluster 
configurations. Request blocks are completely 
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self-describing and consist of four parts: 

1. a standard "header, 

2. request-specific control information, 

3. descriptions of the request data items, and 

4. descriptions of the response data items. 

Each data item is described by memory address, 
size, and source (client or system service 
process) . 


Standard Header 


The format of the standard request block header 
is shown in Table 4-1 below. 


Table 4-1. Format of a Request Block Header. 



Size 

Offset 

Field 

(bytes ) 

0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 


where 


sCntlnfo 


nReqPbCb 


nRespPbCb 


userNum 


is the number of bytes of control 
information . 

is the number of request 
address/size (pb/cb) pairs. 

is the number of response 
address/maximum size (pb/cbMax) 
pairs . 

is a 16-bit user number that 
uniquely identifies the application 
system. Each application partition 
has a unique user number. The 
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processes in an application 
partition share the same user 
number. A process can obtain its 
user number with the GetUserNumber 
operation (see the "Process 
Management" section) . 

exchResp is the response exchange. 

CAUTION: Be extremely careful in 

specifying the response exchange in 
the request block. Conflicting use 
of exchanges, especially explicit 
use of the default response exchange 
of a process that conflicts with the 
implicit use by procedural calls to 
system services and system common 
procedures, tends to cause 
application systems to malfunction 
in ways that are difficult to 
diagnose . 

ercRet is the status code (returned by the 

system service process). 

rqCode is a request code, a 16-bit value 

that uniquely identifies the desired 
system service. The request code is 
used both to route a request to the 
appropriate system service process 
and to specify to that process which 
of the several services it provides 
is currently requested. 


Request-Specific Control Information 

The request-specific control information consists 
of sCntlnfo bytes that are transmitted from 
client to system service (except for ercRet, 
which is transmitted from system service to 
client) . 


Request Data Item 

Each request data item descriptor consists of the 
4-byte memory address of the request data item 
followed by the 2-byte size of the item. The 
total size (in bytes) of the request data item 
descriptors is six times nReqPbCb. Request data 
items are transmitted from client to system 
service . 
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Response Data Item 


Each response data item descriptor consists of 
(1) the 4-byte memory address of the area into 
which the response data item is to be moved by 
the system service, and (2) the 2-byte maximum 
allowable byte count of the response data item. 
The total size (in bytes) of the response data 
item descriptors is six times nRespPbCbMax . 
Response data items are transmitted from system 
service to client. 


Example 


As an example, consider a request to write one 
sector into a file that has already been 
opened. Assume that the client process is using 
a procedural interface rather than directly using 
the Request and Wait primitives. The client 
process makes a function reference, that is, 
ere = Write (fh, pBuffer, sBuffer, lfa, 
psDataRet) , to the file management system Write 
operation, supplying as arguments: 

o the file handle returned from a previous 

OpenFile operation, 

o the memory address of the first byte of data 
to be written, 

o the count of bytes to be written, 

o the logical file address of the sector into 

which the data is to be written, and 

o the memory address of the word into which the 
count of bytes successfully written is to be 
returned . 

The Write function also returns a status code to 
indicate whether the operation was a success. 

The Write system service illustrates both a 
request data item (the data to be written) for 
which the client process is the source and a 
response data item (the count of bytes 

successfully written) for which the system 

service process is the source. 
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In this example, the procedural interface 
automatically allocates memory on the stack of 
the client process for a request block and 
creates a header containing: 

o the number of bytes of control information 

( 6 ), 

o the number of items of request data (1), 

o the number of items of response data (1), 

o the user number (the default is 0 for the 
application system in the interactive 
partition) , 

o the response exchange (the default response 
exchange of the client process is used 
automatically whenever a system service is 
activated through its procedural interface) , 

o the status code (this is returned by the 
system service process), and 

o the request code (36 is the request code to 
invoke the Write system service) . 

The control information contains: 

o the file handle (2 bytes), and 

o the logical file address (4 bytes). 

The single request data item is described by: 

o the memory address of the data to be written, 
and 

o the count of bytes to be written. 

The single response data item is described by: 

o the memory address of the word into which the 
count of bytes successfully written is to be 
returned, and 

o the size (in bytes) of the word into which 
the count of bytes successfully written is to 
be returned (the number 2 is automatically 
supplied by the procedural interface) . 
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Request Primitive 


The Request primitive is a variant of the Send 
primitive. It directs a request for a system 
service from a client process to the service 
exchange of the system service process. 

The Send primitive accepts any 4-byte field as a 
parameter. This is usually, but not necessarily, 
the address of a message. In contrast, the 
Request and Respond primitives explicitly 
interpret the 4-byte field as the memory address 
of a request block. Before issuing the Request 
primitive, the client process arranges the data 
required for the system service into a request 
block in its memory. 

Unlike Send, Request does not accept an 
identification of an exchange as a parameter. 
Rather, it infers the appropriate service 
exchange by using the request code of the request 
block as an index into the Service Exchange 
Table. The Service Exchange Table is constructed 
at system build, resides in the System Image, and 
translates request codes to service exchanges. 

The use of the Service Exchange Table allows 
request codes to remain invariant among CTOS 
Operating Systems with varying organizations of 
system service processes. This invariance 
facilitates the development of filters and is 
critical to the transparent operation of the 
cluster configuration. 

A companion table, the Local Service Code Table , 
translates each request code to a local service 
code to specify which of the several services of 
the system service process is desired. 


Respond Primitive 

The Respond primitive is only used by a system 
service process to respond to a client process 
that requested the performance of a system 
service . 

The only parameter to the Respond primitive is 
the memory address of the request block of the 
client process. That is, the system service must 
use the same memory address as a parameter to 
Respond that the client process used as a 
parameter to the Request primitive. The exchange 
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to which the response is directed is determined 
by the response exchange (exchResp) field of the 
request block. 

In normal operation, sufficient resources (that 
is, link blocks) are always available for the 
successful execution of the Respond primitive. 
This is because the Request primitive reserves a 
link block for the exclusive use of the 
corresponding Respond primitive. Calls to the 
Respond primitive must exactly match calls to the 
Request primitive. That is, each Request must be 
answered by a Respond, and Respond must never be 
used for any purpose other than to answer a 
Request . 

If a malfunctioning user-written system service 
were to fail to respond to a client process's 
request, unmatched requests would cause all link 
blocks to be reserved and future requests would 
receive the "No link block available" status 
code . 

If an application process inappropriately called 
the Respond primitive, the unmatched Respond 
would cause the count of link blocks reserved to 
be insufficient and might cause another call to 
Respond to receive the "No link block available" 
status code. 


Wait Primitive 


The Wait primitive is used with the Request and 
Respond primitives, as well as with the Send 
primitive. System service processes use Wait to 
suspend execution until a client process requests 
the performance of a system service. Client 
processes use Wait to synchronize their execution 
with the completion of the system service they 
requested. In the context of Request and 

Respond, the message that is queued at an 

exchange is always a request block. 

The Wait primitive first checks whether one or 
more messages are queued at the specified 
exchange . 

If messages are queued, the message that was 
enqueued first is dequeued from the exchange and 
its memory address returned to the calling 
process; the calling process then continues 

execution. 
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If no messages are queued, the- Process Control 
Block of the calling process is queued at the 
exchange and the process is placed into the 
waiting state. In the waiting state, the process 
stops executing and relinquishes control of the 
processor. The calling process remains in the 
waiting state until another process queues a 
message at the specified exchange. The calling 
process then leaves the waiting state and is 
placed into the ready state. The memory address 
of the message queued at the exchange by the 
other process is returned to the calling process 
and it resumes execution when it becomes the 
highest priority ready process. 


Interstation Communication 

The interstation communication (ISC) facility is 
an upward-compatible extension of the 
interprocess communication facility. When a 
client process requests a system service, a 
request block is constructed that contains all 
the information necessary to describe the desired 
function . 

In a standalone workstation, the request block is 
queued at the exchange of the system service 
process that actually performs the desired 
function. 


CWS Agent Service Process 

In a cluster workstation (CWS), however, if the 
function is to be performed at the master 
workstation, the request block is queued at the 
exchange of the CWS Agent Service Process. The 
CWS Agent Service Process converts interprocess 
requests to interstation messages for 
transmission to the master workstation. The CWS 
Agent Service Process is included at system build 
in a System Image that is to be used on a CWS. 


Master Workstation Agent Service Process 

The System Image used at the master workstation 
is built to include a corresponding service 
process: the master workstation Agent Service 
Process. The master workstation Agent Service 
Process reconverts the interstation message to an 
interprocess request that it queues at the 
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exchange of the master workstation system service 
process that actually performs the desired 
function. Note that the Service Exchange Table 
that translates request code to service exchange 
at the master workstation is necessarily 
different from the table at the CWS. When the 
system service process at the master workstation 
responds, the response is routed through the 
master workstation Agent Service Process, the 
high-speed data link, and the CWS Agent Service 
Process before being queued at the response 
exchange in the CWS that was specified in the 
request block. 

The format of request blocks is designed to allow 
the CWS and master workstation Agent Service 
Processes to convert between interprocess 
requests and interstation messages very 
efficiently and with no external information. 
Because request blocks are completely self- 
describing, the Agent Service Processes can 
transfer requests and responses between the 
master workstation and CWSs without any knowledge 
of what function is requested or how it is to be 
performed . 


Interstation Request/Response Message 

An interstation request message consists of: 


o 

a header. 



o 

control information. 



o 

the size and actual text of 
item, and 

each request data 

o 

the maximum allowed 
data item. 

size 

of each response 

An 

interstation response 

message consists of: 

o 

a status code, and 



o 

the actual size and 
data item. 

text 

of each response 


4-24 


CTOS* Operating System Manual 



The CWS Agent Service Process forms an 
interstation request message by copying the 
header and control information from the request 
block, moving the actual text of the request data 
items into the message, and including a 
specification of the maximum allowed sizes of the 
response data items. 

After receiving the interstation response 
message, the CWS Agent Service Process stores the 
status code into the request block and moves the 
text of the response data items into the memory 
areas specified for them by the request block. 
This transformation scheme ensures that no 
redundant or extraneous information is 
transmitted between the master workstation and 
CWSs . 


IPC Management 4-25 



OPERATIONS : PRIMITIVES 


Interprocess 
the operations 

Check 

PSend 

Request 

Respond 

Send 

Wait 


communication management provides 
listed below. 

dequeues the message (if any) 
that was enqueued first at the 
specified exchange. Returns 
the status code "No message 
available" (14) if none are 
queued . 

a privileged send used by 
interrupt handlers. Sends the 
specified message to the 
specified exchange. 

requests a system service by 
sending a request block to the 
exchange of the system service 
process . 

notifies a client process that 
the requested system service 
was performed by sending the 
request block of the client 
process back to the response 
exchange specified in the 
request block. 

sends the specified message to 
the specified exchange. 

dequeues the message (if any) 
that was enqueued first at the 
specified exchange. Causes the 
calling process to be placed 
into the waiting state if no 
messages are enqueued. 
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Check 


Description 

The Check primitive checks whether messages are 
queued at the specified exchange. If messages 
are queued, then the message that was enqueued 
first is dequeued and its memory address is 
returned to the calling process. If no messages 
are queued, then status code 14 ("No message 
available") is returned. 

The Check primitive, unlike the Wait primitive, 
never causes the calling process to be placed 
into the waiting state. 

Procedural Interface 

Check (exchange, ppMsgRet) : ErcType 
where 

exchange is the identification of the 

exchange to check. 

ppMsgRet is the memory address of a 4-byte 

field into which the memory address 
of the message that was enqueued 
first at the exchange, if any, is 
returned . 

Request Block 

Check is a Kernel primitive. 
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PSend 


Description 

The PSend primitive, a privileged Send primitive 
used by interrupt handlers, checks whether 
processes are queued at the specified exchange. 
If processes are queued, then the process that 
was enqueued first is dequeued, given the memory 
address of the message, and placed into the ready 
state . 

If no processes are waiting at the exchange, then 
the message is queued at the exchange. 

PSend uses a special pool of link blocks that are 
reserved at system build (see the System 
Programmer 1 s Guide ) . 

Procedural Interface 

PSend (exchange, pMsg): ErcType 
where 

exchange is the identification of the 

exchange to which the message is 
sent . 

pMsg is the memory address of the message 

(or a 4-byte field of information 
whose interpretation is agreed upon 
by the sending and receiving 
processes ) . 

Request Block 

PSend is a Kernel primitive. 
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Request 

Description 


The Request primitive requests a Convergent- or 
user-written system service by sending a request 
block to the service exchange of the system 
service process. 

A client process uses the Request primitive 
indirectly when it uses the procedural interface 
to a system service or directly when it is 
necessary to overlap its own execution with the 
performance of the service. 

The Request primitive infers the appropriate 
service exchange by using the request code of the 
request block as an index into the Service 
Exchange Table. The use of the Service Exchange 
Table allows request codes to remain invariant 
among CTOS Operating Systems with varying 
organizations of system service processes. This 
invariance facilitates the development of filters 
and is critical to the transparent operation of 
the cluster configuration. 

The client process must use the AllocExch 
operation (see the "Exchange Management" section) 
to acquire an exchange identification to place 
into the exchResp field of the request block. 

There must not be conflicting uses of the 
response exchange specified in the request block; 
such conflict can cause malfunction of the 
application system that is difficult to diagnose. 

Procedural Interface 

Request (pRq) : ErcType 

where 

pRq is the memory address of the request 

block . 

Request Block 

Request is a Kernel primitive. 
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Respond 

Description 


The Respond primitive is only used by a system 
service process to respond to a client process. 
After the system service process has completed 
the processing of a service request, it invokes 
Respond to send the request block of the client 
process back to the response exchange specified 
in the request block. 

The Respond primitive accepts the memory address 
of the request block of the client process as its 
only parameter; the system service process must 
use the same memory address as a parameter to the 
Respond primitive that the client process used as 
a parameter to the Request primitive. The 
exchange to which the response is directed is 
determined by the exchange response field of the 
request block. 

Calls to the Respond primitive must exactly match 
calls to the Request primitive; that is, each 
Respond must answer a Request and each Request 
must be answered by a Respond. 

A link block is reserved by the corresponding 
Request primitive to ensure the successful 

execution of the Respond primitive. 

The use of the Respond primitive within an 
application system would cause catastrophic 
mismanagement of link blocks and termination of 
CTOS operation. See the discussion in the System 
Programmer's Guide for a complete explanation. 

Procedural Interface 

Respond (pRq) : ErcType 

where 

pRq is the memory address of the same 

request block that the system 
service process received from its 
exchange . 

Request Block 

Respond is a Kernel primitive. 
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Send 


Description 

The Send primitive checks whether processes are 
queued at the specified exchange. If processes 
are queued, then the process that was enqueued 
first is dequeued, given the memory address of 
the message, and placed into the ready state. If 
such a process has a higher priority than the 
calling process, it is scheduled for immediate 
execution and the calling process remains 

preempted until the higher priority process 
reenters the waiting state. 

If no processes are waiting at the exchange, then 
the message is queued at the exchange. 

Procedural Interface 

Send (exchange, pMsg) : ErcType 
where 

exchange is the identification of the 

exchange to which the message is 
sent . 

pMsg is the memory address of the message 

(or a 4-byte field of information 
whose interpretation is agreed upon 
by the sending and receiving 
process) . 

Request Block 

Send is a Kernel primitive. 
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Wait 


Description 

The Wait primitive checks whether messages are 
queued at the specified exchange. If messages 
are queued, then the message that was enqueued 
first is dequeued and its memory address is 
returned to the calling process; the calling 
process then continues execution. 

If no messages are queued, then the Process 
Control Block of the calling process is queued at 
the exchange and the process is placed into the 
waiting state. In the waiting state, the process 
stops executing and relinquishes control of the 
processor. The calling process remains in the 
waiting state until another process queues a 
message at the specified exchange using the Send, 
PSend, Request, or Respond primitives. The 
calling process then leaves the waiting state and 
is placed into the ready state. The memory 
address of the message queued at the exchange by 
the other process is returned to the calling 
process, which resumes execution when it becomes 
the highest priority ready process. 

Procedural Interface 

Wait (exchange, ppMsgRet) : ErcType 

where 

exchange is the identification of the 

exchange at which to wait. 

ppMsgRet is the memory address of a 4-byte 

field into which the memory address 
of the message, if any, that was 
enqueued first at the exchange is 
returned . 

Request Block 

Wait is a Kernel primitive. 
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5 EXCHANGE MANAGEMENT 


OVERVIEW 


The exchange management facility supports the 
dynamic allocation and deallocation of 
exchanges. For more information about exchanges, 
see the "Interprocess Communication Management" 
section . 


Exchange Management 
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CONCEPTS 


Exchange 


An exchange is the path over which messages are 
communicated from process to process (or from 
interrupt handler to process) . An exchange 
consists of two first-in, first-out queues: one 

of processes waiting for messages, the other of 
messages for which no process has yet waited. An 
exchange is referred to by a unique 16 -bit 
integer . 

Processes or messages, but not both, can be 
queued at an exchange at any given moment. If a 
process waits at an exchange at which messages 
are queued, then the message that was enqueued 
first is dequeued and its memory address given to 
the process; the process then continues execu- 
tion. Similarly, if a message is sent to an 
exchange at which processes are queued, then the 
process that was enqueued first is dequeued, 
given the address of the message, and placed into 
the ready state . 

Exchange Allocation 

Exchanges are allocated in three ways: 

o Exchanges for system service processes are 
allocated at system build. 

o Exchanges can be dynamically allocated and 
deallocated using the AllocExch and Dealloc- 
Exch operations. 

o When a process is created, its creator gives 
it a unique default response exchange . (See 
the "Interprocess Communication Management" 
section.) A process can determine the 
identification of its own default response 
exchange by using the QueryDefaultRespExch 
operation. 

In a compact system, all allocated exchanges are 
deallocated when the application system exits. 
In a system where multiple application systems 
can execute simultaneously, only the exchanges of 
an exiting application system are deallocated. 

Operations and data structures for interpartition 
communication are described in the "Application 
Partition Management" section. 
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OPERATIONS: PROCEDURES AND SERVICES 


Exchange management operations are categorized by 
function in Table 5-1 below. 


Table 5-1. Exchange Management Operations by Function. 

Allocation 

Deallocation 

AllocExch 

DeallocExch 

Inquiry 


QueryDefaultRespExch 



Allocation 


AllocExch 


allocates an exchange. 


Deallocation 


Deal locExch 


deallocates an exchange. 


Inquiry 


QueryDefaultRespExch 

allows a process to determine 
the identification of its own 
default response exchange. 
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AllocExch 


Description 


The AllocExch service allocates an exchange. 
Procedural Interface 

AllocExch (pExchRet) : ErcType 
where 

pExchRet is the memory address of a word into 

which the identification of the 
allocated exchange is returned. 

Request Block 

sExchMax is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

40 

12 

reserved 

6 


18 

pExchRet 

4 


22 

sExchMax 

2 

2 
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DeallocExch 


Description 

The DeallocExch service deallocates an exchange. 

Procedural Interface 

DeallocExch (exchange): ErcType 
where 

exchange is the identification of the 

exchange to deallocate. This 

identification must have been 
obtained using the AllocExch 

operation . 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

41 

12 

exchange 

2 
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QueryDefaultRespExch 

Description 


The QueryDefaultRespExch procedure allows a 
process to determine the identification of its 
own default response exchange. 

Procedural Interface 

QueryDefaultRespExch (pExchRet) : ErcType 
where 

pExchRet is the memory address of a word into 

which the identification of the 
default response exchange of the 
inquiring process is returned. 


Request Block 


QueryDefaultRespExch is a system common 
procedure . 
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6 MEMORY MANAGEMENT 


OVERVIEW 

The memory management facility supports the 
dynamic allocation and deallocation of areas of 
memory for code, data, etc., by each application 
system in its own partition. 


Types of Memory 


Two types of memory allocation are available to 
the application system: long-lived and short- 
lived. Within each application partition, long- 
lived memory expands upward from low memory 
locations, while short-lived memory expands 
downward from high memory locations. The OS 
allocates short-lived memory for application 
tasks . 

Both long-lived and short-lived memory can be 
dynamically allocated and deallocated by requests 
to OS system services. 

When the execution of an application system is 
terminated, the short-lived memory of its 
partition is automatically deallocated. 

Long-lived memory is deallocated only at the 
explicit request of each application system. 
Therefore, long-lived memory is useful for 
passing information from an application system to 
a succeeding application system in the same 
partition . 
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CONCEPTS 


Addressing Memory 

The Convergent Information Processing System has 
a one megabyte address space. Each of the 
1,048,576 bytes in the address space has a unique 
20-bit physical memory address . However, 
software does not use physical memory 
addresses. Software identifies specific bytes of 
memory by using logical memory addresses. 

A logical memory address is a 32-bit entity 
consisting of a 16-bit segment base address and a 
16-bit offset. 

A segment base address is the high-order 16-bits 
of the 20-bit physical memory address of a 
hardware segment. (The low-order 4 bits are 
implicitly 0.) The CS, DS, SS, and ES segment 
registers of the 8086 processor contain segment 
base addresses. 

The offset is the distance, in bytes, of the 
target location from the beginning of the 
hardware segment. The physical memory address of 
a byte is computed by multiplying the segment 
base address by 16 and adding the offset. 

A byte of memory does not have a unique logical 
memory address. Rather, any of the 4096 
combinations of segment base address and offset 
refer to the same byte of memory. Whenever the 
term memory . address is used in this Manual, it 
refers to logical memory address. 


Segments 


A segment is a contiguous (usually large) area of 
memory that consists of an integral number of 
paragraphs. A paragraph is 16 bytes of memory 
whose physical memory address is a multiple of 
16. 


Hardware segments can be adjacent, disjoint, 
partially overlapping, or completely 
overlapping. A physical memory location can be 
contained in multiple hardware segments. 

Software segments are nonoverlapping hardware 
segments that contain single, logical entities. 
It is conventional to address a byte within a 
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software segment by using a logical memory 
address whose segment base address points to the 
first byte of the segment and whose offset is the 
physical memory address of the addressed byte 
minus the physical memory address of the first 
byte of the segment. This convention limits the 
size of a software segment to 65,536 bytes. 


Code, Static Data, and Dynamic Data Segments 

There are three types of software segments: 
code, static data, and dynamic data. Each type 
of segment can be either shared or nonshared. 

A code segment contains only processor 
instructions ( code ) and is never modified once it 
is loaded into memory. This characteristic 
permits several processes to execute instructions 
from the same code segment. It also allows the 
virtual code segment management facility (see the 
section of that name) to reload code segments 
from the run file as needed without saving the 
copy of the segment previously in memory. 

A data segment contains data. It can also 
contain code, although this is not recommended. 
There are no restrictions on modifying the 
contents of a data segment. If a data segment is 
shared among processes, concurrency control is 
the responsibility of those processes. 

A static data segment is automatically loaded 
into memory when its containing task image is 
loaded . 

A dynamic data segment is allocated by a request 
from an executing process to the memory 
management facility. 

Code and static data segments are created by 
compiling and/or assembling source programs into 
object modules and linking the object modules 
into task images. 

A task image is a program stored in a run file 
that contains code and/or static data segments. 
When requested, the task management facility 
loads the task image into memory and adjusts any 
logical memory addresses that exist in either 
code or data segments to reflect the memory 
address at which the task is loaded. 
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If the virtual code segment management facility 
is in use, all the static data segments, but only 
the resident code segment, are loaded into 
memory. The nonresident code segments are loaded 
into memory only as needed . 

The Linker utility reads segments from object 
module files and combines them according to their 
segment names, class names, and directives from 
the user. (See the Linker/Librarian and Assembly 
Language Manuals . ) 

A task image that was created by linking object 
modules produced by the Pascal and/or FORTRAN 
compilers consists of one code segment for each 
object module included in the link and a single 
static data segment. The single static data 
segment (DGroup) combines the static data and 
stack requirements of all the object modules. A 
task image of this form is considered standard; 
assembly language programmers are urged to adopt 
this standard unless other considerations are 
overriding. (The COBOL compiler and BASIC 
interpreter do not produce object modules.) 


Memory Organization 

The memory organization of an application 
partition in a compact system (in which 
application systems can be executed one at a 
time) differs from that of a system in which 
multiple application systems can be executed 
simultaneously. 

Figure 6-1 shows the memory organization of the 
application partition in the compact system. 

Figure 6-2 shows the memory organization of an 
application partition in a system in which 
multiple applications can be executed 
simultaneously. In this system, both the primary 
and secondary application partitions have the 
same memory organization. 
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Low End of Memory 


High End of Memory 


Long-Lived Memory 


Common Pool of Unallocated Memory 


Short-Lived Memory 


Secondary Task 2 
Secondary Task 1 
Primary Task 


Figure 6-1. Memory Organization of the Application Partition in a 
Compact System. 


Long-Lived and Short-Lived Memory 

Two types of memory allocation are available to 
each application system: long-lived and short- 
lived. Within each application partition, long- 
lived memory expands upward from low memory 
locations, while short-lived memory expands 
downward from high memory locations. The OS 
allocates short-lived memory for application 
tasks . 

All currently unallocated memory in an 
application partition is in a contiguous area 
called the common memo ry pool . Memory can be 
allocated from both ends of the pool. There is 
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Figure 6-2. Memory Organization of an Application Partition in a System 

Allowing Simultaneous Execution of Multiple Application Systems. 
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Operations 


The AllocMemoryLL and AllocMemorySL operations 
allocate long-lived and short-lived memory 
segments, respectively, in an application 
partition. Note, however, that the 
A1 locAl IMemory SL operation can allocate more than 
65,536 bytes, and thus the entire area allocated 
by this operation is not necessarily addressable 
as a single segment. 

The DeallocMemoryLL and DeallocMemorySL 
operations deallocate long-lived and short-lived 
memory segments, respectively, in an application 
partition. The ResetMemoryLL operation 
deallocates all long-lived memory in an 
application partition. 


Deallocations 


Relative to allocations from one end of an 
application partition's memory, deallocations 
must occur in exactly the opposite sequence. 
That is, the user must follow a last allocated, 
first deallocated discipline when deallocating 
either long-lived or short-lived memory. For 
example, if an application system allocates 
short-lived memory segments A, B, and C, it then 
deallocates them in the order C, B, A. 

Thus the motion of the borders (the dashed lines 
in Figures 6-1 and 6-2 above) of the common pool 
of memory in an application partition resembles 
the playing of an accordion: the borders 
converge when memory is allocated and diverge 
when memory is deallocated. This scheme is 
efficient because all unallocated memory is in a 
common pool and simple because the OS has to 
remember only the addresses of the next (long- 
lived and short-lived) segments to allocate, not 
the addresses of all allocated segments. 


Long-Lived Memory Uses 

The long-lived memory in an application partition 
is used for: 

o parameters passed from one application system 
to a succeeding application system in the 
same partition, and 
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o 


user data that is to be processed by- 
succeeding application systems in the same 
partition . 

Long-lived memory allocations are returned to the 
common pool of unallocated memory in an 
application partition only upon explicit request 
of the application system. 


Short-Lived Memory Uses 

The short-lived memory in an application 
partition is used by the OS to contain the code 
and static data segments of each task. It is 
also allocated by application processes for use 
as dynamic data segments for data that is to be 
processed only by the current application 
system. Other common uses of short-lived memory 
are input/output buffers and the Pascal heap. 

Short-lived memory allocations are returned to 
the common pool of unallocated memory whenever 
the application system is replaced (in any 
application partition by the Chain, ErrorExit, or 
Exit operations, or in the primary application 
partition by the key combination ACTION- 
FINISH) . (See the "Task Management" section.) 


Virtual Code Segment Management 

See the "Virtual Code Segment Management" section 
for how tasks of an application system are 
handled when they require an area larger than the 
available physical memory in an application 
partition . 
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OPERATIONS : SERVICES 


Memory management operations are categorized by 
function in Table 6-1 below. 


Table 6-1. Memory Management Operations by Function. 

Allocation 

Deallocation 

A1 locAl IMemory SL 

Deal locMemo ryLL 

All ocMemo ryLL 

Deal locMemo rySL 

A1 locMemory SL 

ResetMemoryLL 

Inquiry 


QueryMemAvail 



Allocation 


AllocAllMemorySL 

AllocMemoryLL 
A1 locMemory SL 

Deal location 

Deal 1 ocMemo ryLL 
DeallocMemorySL 
ResetMemoryLL 


allocates the largest possible 
short-lived memory segment in 
an application partition. 

allocates a long-lived memory 
segment in an application 
partition . 

allocates a short-lived memory 
segment in an application 
partition. . 


deallocates a long-lived memory 
segment in an application 
partition . 

deallocates a short-lived 
memory segment in an 
application partition. 

deallocates all long-lived 
memory in an application 
partition . 
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Inquiry 


QueryMemAvail 


returns the size of all 
available memory in an 
application partition. 
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A1 1 oc A1 1 Memo r y SL 
Description 

The AllocAllMemorySL service allocates the 
largest possible short-lived memory segment 
within an application partition. 

Procedural Interface 

AllocAl IMemorySL (pcParagraphRet, 

ppSegmentRet ) : ErcType 


where 

pcParagraphRet 

is the memory address of a word into 
which the count of bytes available 
(divided by 16) is returned. 

ppSegmentRet is the memory address of 4 bytes 
into which the memory address of the 
allocated segment is returned. The 
low-order 2 bytes contain the 
offset, which is always 0. The 

high-order 2 bytes contain the 
segment base address of the 

allocated segment. 
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Request Block 


scParagraphMax is always 2 and spSegmentMax is 
always 4. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

2 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

46 

12 

reserved 

6 


18 

pc Paragraph Ret 

4 


22 

scParagraphMax 

2 

2 

24 

ppSegmentRet 

4 


28 

spSegmentMax 

4 

4 


6-12 


CTOS™ Operating System Manual 



A1 locMemoryLL 
Description 


The A1 locMemoryLL service allocates a long-lived 
memory segment of the specified size within an 
application partition. 

Procedural Interface 

A1 locMemoryLL (cBytes, ppSegmentRet) : ErcType 
where 

cBytes is the desired segment size. 

ppSegmentRet is the memory address of 4 bytes 
into which the memory address of the 
allocated segment is returned. The 
low-order 2 bytes contain the 
offset, which is always 0. The 

high-order 2 bytes contain the 
segment base address of the 

allocated segment. 

Request Block 

spSegmentMax is always 4. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

44 

12 

cBytes 

2 


14 

reserved 

4 


18 

ppSegmentRet 

4 


22 

spSegmentMax 

2 

4 
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A1 locMemorySL. 

Description 


The A1 locMemo rySL service allocates a short-lived 
memory segment of the specified size within an 
a pp licat io n partition. 

Procedural Interface 

A1 locMemorySL (cBytes, ppSegmentRet ) : ErcType 
where 

cBytes is the desired segment size. 

ppSegmentRet is the memory address of 4 bytes 
into which the memory address of the 
allocated segment is returned. The 
low-order 2 bytes contain the 
offset, which is always 0. The 
high-order 2 bytes contain the 
segment base address of the 
allocated segment. 

Request Block 

spSegmentMax is always 4. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

42 

12 

cBytes 

2 


14 

reserved 

4 


18 

ppSegmentRet 

4 


22 

spSegmentMax 

2 

4 
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Deal locMemoryLL 
Description 


The Deal locMemoryLL service deallocates a long- 
lived memory segment of the specified size within 
an application partition. Segments must be 
deallocated in a sequence exactly opposite the 
one in which they were allocated (that is, last 
allocated, first deallocated) . 

Procedural Interface 

Deal locMemoryLL (pSegment, cBytes) : ErcType 
where 

pSegment is the memory address of the segment 

to deallocate. The offset portion 
must be 0. pSegment should be the 
same memory address that was 
returned by the corresponding 
AllocMemoryLL operation. 

cBytes is the size (in bytes) of the 

segment to deallocate. cBytes 

should be the same value that was 
passed to the corresponding 
AllocMemoryLL operation. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

45 

12 

cBytes 

2 


14 

pSegment 

4 
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Deal locMemorySL 
Description 


The Deal locMemorySL service deallocates a short- 
lived memory segment of the specified size within 
an application partition. Segments must be 
deallocated in a sequence exactly opposite the 
one in which they were allocated (that is, last 
allocated, first deallocated) . 

Procedural Interface 

Deal locMemorySL (pSegment, cBytes) : ErcType 
where 

pSegment is the memory address of the segment 

to deallocate. The offset portion 
must be 0. pSegment should be the 
same memory address that was 
returned by the corresponding 
A.1 locMemorySL operation. 

cBytes is the size (in bytes) of the 

segment to deallocate. cBytes 

should be the same value that was 
passed to the corresponding 
AllocMemorySL operation. 


Request Bloch 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

43 

12 

cBytes 

2 


14 

pSegment 

4 
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Que ryMemAva i 1 
Description 


The QueryMemAvail service returns the size (in 
16-byte paragraphs) of all currently available 
memory in an application partition. Because of 
the way in which memory is organized, it is 
possible to allocate segments from available 
memory using both the AllocMemoryLL and 
AllocMemorySL operations. 

Procedural Interface 

QueryMemAvail (pcParagraphRet) : ErcType 
where 

pcParagraphRet 

is the memory address of a word into 
which the count of bytes available 
(divided by 16) is returned. 


Request Bloch 


scParagraphMax is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

48 

12 

reserved 

6 


18 

pcParagraphRet 

4 


22 

scParagraphMax 

4 

2 
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Re se tMemoryLL 
Description 


The ResetMemoryLL service deallocates all long- 
lived memory within an application partition. An 
application system in the primary application 
partition should not use ResetMemoryLL unless 
another Executive was substituted for the 
Convergent Executive; this is because the 
Convergent Executive depends on part of the 
contents of long-lived memory. 

Procedural Interface 

ResetMemoryLL: ErcType 

Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

47 
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7 TASK MANAGEMENT 


OVERVIEW 


Th e task management facility supports the 
asynchronous execution of several loosely and/or 
tightly coupled application software elements 
(tasks) performing related portions of a single 
application system. 

An application system consists of one or more 
tasks. A task consists of code, data, and one or 
more processes. The code and data can be unique 
to the task or shared with other tasks. 

An application system can be executed in each 
application partition. Multiple application 
systems can be executed simultaneously, each in 
its own partition. (See the “Application 
Partition Management" section.) 

Task management provides operations to (1) 
replace an entire application system (all tasks 
within an application partition) with a single 
new task and (2) incrementally add a task to a 
current application system. A task is always 
loaded into the highest available memory location 
within the application partition and has a single 
process associated with it when it is first 
loaded. Additional processes can be created 
dynamically. 
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CONCEPTS 


Application System 

An application system is the name for all the 
tasks currently loaded in a specific application 
partition. These tasks can be loosely or tightly 
coupled, but all perform related portions of the 
same application system. These tasks execute 
asynchronously. A task can be added to an 
application system but not removed from it. 


Task 


A task is an executable program that consists of 
code, data, and one or more processes. The code 
and data can be unique to the task or shared with 
other tasks. 

A task image is the disk-resident image of an 
executable program. It is created by compiling 
and/or assembling source language modules into 
object modules and linking the object modules 
together. A disk file that contains a task image 
is called a run file . A task image contains code 
and/or data segments. 


Code and Data Segments 

A code segment contains only processor 
instructions (code) and is never modified once it 
is loaded into memory. This characteristic 
permits several processes to execute instructions 
from the same code segment. It also allows the 
virtual code segment management facility (see the 
section of that name) to reload code segments 
from the run file as needed without saving the 
copy of the segment previously in memory. 

A data segment contains data. It can also 
contain code, although this is not recommended. 
There are no restrictions on modifying the 
contents of a data segment. If a data segment is 
shared among processes, concurrency control is 
the responsibility of those processes. 

A data segment that is automatically loaded into 
memory when its containing task image is loaded 
is called a static data segment , to differentiate 
it from a dynamic data segment. A dynamic data 
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segment is allocated by a request from the 
executing process to the memory management 
facility . 

The Linker utility reads segments from object 
module files and combines them according to their 
segment names, class names, and directives from 
the user. (See the Linker/Librarian and Assembly 
Language Manuals . ) ~ - 

A task image that was created by linking object 
modules produced by the Pascal and/or FORTRAN 
compilers consists of one code segment for each 
object module included in the link and a single 
static data segment. The single static data 
segment (DGroup) combines the static data and 
stack requirements of all the object modules. A 
task image of this form is considered standard; 
assembly language programmers are urged to adopt 
this standard unless other considerations are 
overriding. (The COBOL compiler and BASIC 
interpreter do not produce object modules.) 


Loading a Task 


Loading a task consists of reading the task image 
into the short-lived memory of an application 
partition and adjusting any logical memory 
addresses (intersegment references) that exist in 
either code or data segments to reflect the 
memory address at which the task is loaded. 

Short-lived memory is allocated from the high- 
address end of the common pool of unallocated 
memory of the application partition and is 
returned to the common pool whenever the 
application system is replaced (in any 
application partition by the Chain, ErrorExit, or 
Exit operations, or in the primary application 
partition by the key combination ACTION-FINISH) . 

If the virtual code segment management facility 
is in use, all the static data segments, but only 
the resident code segment, are loaded into 
memory. The nonresident code segments are loaded 
into memory only as needed. 

Virtual code segment management is available to 
the primary or a secondary task of an application 
partition. However, a secondary task cannot be 
virtual if the primary task already uses virtual 
code segment management. 
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Exit Run File 


Primary tasks are those loaded by the Chain, 
ErrorExit, or Exit operations (see the "Task 
Management" section) , or the LoadPrimaryTask 
operation (see the "Application Partition 
Management" section) . Secondary tasks are those 
loaded by the task management LoadTask operation. 


An exit run file is a user-specified file that is 
loaded and activated when an application system 
exits. Each application partition has its own 
exit run file. 

An application system can specify an exit run 
file for its partition with the SetExitRunFile 
operation. An application system can determine 
the exit run file of its partition with the 
QueryExitRunFile operation. 

An exit run file is a primary task that can, in 
turn, load additional tasks into its partition 
with the LoadTask operation. 

In the primary application partition, if no exit 
run file is specified, the system will 
malfunction and reboot itself. If the exit run 
file cannot be read, it displays the message 
"Cannot load exit run file" and a status code 
indicating the type of error that occurred. If 
the exit run file is on a floppy disk, the user 
can insert a floppy disk with the appropriate 
exit run file and the system will resume loading 
of the exit run file. 


Operations 


The task management facility provides six 
operations: Chain, ErrorExit, Exit, LoadTask, 
QueryExitRunFile, and SetExitRunFile. 

Chain, ErrorExit, and Exit terminate all 
application processes and deallocate all short- 
lived memory in an application partition before 
loading the succeeding application system and 
creating a single process to execute it. In 
addition, ErrorExit and Exit pass an abnormal and 
normal status code, respectively, to the 
succeeding application system in the same 
application partition. 
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The LoadTask operation, in contrast, preserves 
all current application processes and short-lived 
memory allocations in the application partition 
while loading and activating an additional task 
and creating an additional process to execute it. 

The SetExitRunFile operation establishes a new 
exit run file for an application partition. The 
QueryExitRunFile operation returns the name, 
password, and priority of the exit run file of an 
application partition. 
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OPERATIONS: PROCEDURES AND SERVICES 


Task management 
below . 

Chain 

ErrorExit 

Exit 

LoadTask 

QueryExitRunFile 

SetExitRunFile 


provides the operations listed 


replaces the current 
application system in an 
application partition with the 
specified run file. 

terminates the current 
application system in an 
application partition and 
passes an abnormal status code 
to the exit run file. 

terminates the current 
application system in an 
application partition and 
passes a normal status code to 
the exit run file. 

loads and activates an 
additional task as part of the 
current application system in 
an application partition. 


returns the name, password, and 
priority of the exit run file 
of an application partition. 

establishes a new exit run file 
for an application partition. 
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The Chain service replaces a current application 

system with a specified run file. Chain returns 

control to the calling process only if an error 

condition is detected. 

Chain: 

1. Verifies that the specified run file exists, 
that it can be opened for Read using the 
password provided, that it contains a valid 
task image, and that the task image fits in 
the application partition. 

2. Places the status code in the Application 
System Control Block of the application 
partition . 

3. Disconnects interrupt handlers of the 
application partition and terminates all 
processes of the application partition. 

4. Terminates keyboard (primary appliction 
partition only), timer, and communications 
requests, and waits until all disk and 
printer input/output activity has ceased. 

5. In the primary application partition only, 
resets the keyboard to character mode. 
Discards the content of the type-ahead buffer 
if the keyboard was in unencoded mode and/or 
the status code is nonzero. 

6. In the primary application partition only, 
reenables the ACTION-FINISH feature and 
discards the action code (if any). 

7. In the primary application partition only, 
closes the submit or recording file if the 
status code is nonzero. 

8. Closes all files opened for the application 
partition except those marked long-lived (by 
the OpenFileLL or SetFhLongevity operations; 
see the "File Management" section) . 

9. Releases for reuse all application partition 
memory that was allocated as short-lived. 
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10. Allocates a short-lived memory segment in the 
application partition that is large enough to 
contain the task image from the specified run 
file . 

11. Reads the task image from the run file into 
the application partition. 

12. Relocates all intersegment references to 
accommodate the memory address at which the 
task image is loaded. 

13. Creates a process to be scheduled at the 

specified priority. The initial values 

loaded into the segment registers (CS, DS, 
SS, ES), the Stack Pointer (SP), and the 
Instruction Pointer (IP) are derived from 
information in the run-file header. 

Chain has no effect on the allocation of long- 
lived memory. 

If the task requires virtual code segment 
management, the run file is left open to 
accommodate code swapping. The file handle of 

the open run file is placed in the Application 
System Control Block of the application 
partition. 


Procedural Interface 

Chain (pbFileSpec, cbFileSpec, pbPassword, 

cbPassword, priority, ercTermination, 
f Debug): ErcType 

where 


pbFileSpec 

cbFileSpec describe a character string of the 
form {node} [volname] <dirname> file- 
name . 


pbPassword 

cbPassword 


describe 

directory, 

authorizes 

file. 


either the volume, 
or file password that 
access to the specified 


priority is the priority (0-254, with 0 the 

highest) at which to schedule the 
newly created process for execution. 
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ercTermination 

is a 16-bit status code to be placed 
in the Application System Control 
Block of the application partition 
for examination by the run file. In 
the primary application partition 
only, a nonzero status code causes 
the content of the type-ahead buffer 
to be discarded and the submit or 
recording file to be closed. 

fDebug indicates whether the run file is to 

be debugged. TRUE indicates it is 
to be debugged and therefore not 
scheduled for execution; FALSE 
indicates it is to be scheduled for 
execution. If fDebug is TRUE, then 
the Debugger is entered 

automatically as soon as the task 
image is loaded into the application 
partition. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

28 

12 

priority 

2 


14 

ercTermination 

2 


16 

fDebug 

2 


18 

pbFileSpec 

4 


22 

cbFileSpec 

2 


24 

pb Pas sword 

4 


28 

cbPas sword 

2 
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ErrorExit 


Description 


The ErrorExit procedure terminates the current 
application system and passes an abnormal status 
code to the specified exit run file. ErrorExit 
never returns to the calling process. 

ErrorExit is exactly like the Exit operation 
except that the status code in ErrorExit is 
explicit . 

ErrorExit : 

1. Verifies that the specified exit run file 

exists, that it contains a valid task image, 
and that the task image fits in the 

application partition memory (the OS 
terminates if this verification fails) . 

2. Places the specified abnormal status code in 
the Application System Control Block of the 
application partition. 

3. Disconnects interrupt handlers of the 
application partition and terminates all 
processes of the application partition. 

4. Terminates keyboard (primary application 
partition only) , timer, and communications 
requests, and waits until all disk and 
printer input/output activity has ceased. 

5. In the primary application partition only, 
resets the keyboard to character mode. 
Discards the content of the type-ahead buffer 
if the keyboard was in unencoded mode and/or 
the status code is nonzero. 

6. In the primary application partition only, 
reenables the ACTION-FINISH feature and 
discards the action code (if any). 

7. In the primary application partition only, 
closes the submit or recording file if the 
status code is nonzero. 

8. Closes all files opened for the application 
partition except those marked long-lived (by 
the OpenFileLL or SetFhLongevity operations; 
see the "File Management" section) . 
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9. Releases for reuse all application partition 
memory that was allocated as short-lived. 

10. Allocates a short-lived memory segment large 
enough to contain the task image from the 
specified exit run file. If sufficient 
application partition memory to load the exit 
run file cannot otherwise be allocated, then 
long-lived memory is reset (that is, released 
to the common pool of unallocated memory) 
before the exit run file is loaded. 

11. Reads the task image from the run file into 
the application partition. 

12. Relocates all intersegment references to 
accommodate the memory address at which the 
task image is loaded. 

13. Creates a process to be scheduled at the 
default priority. The initial values loaded 
into the segment registers (CS, DS, SS, ES), 
the Stack Pointer (SP), and the Instruction 
Pointer (IP) are derived from information in 
the run-file header. 

ErrorExit has no effect on the allocation of 
long-lived memory except as noted in step 10 
above. If necessary, the exit run file is left 
open to accommodate code swapping of the exit run 
file. The file handle of the open run file is 
placed in the Application System Control Block of 
the application partition. 

Procedural Interface 

Call ErrorExit ( ercTermination) 
ercTermination 

is a 16-bit status code to be placed 
in the Application System Control 
Block of the application partition 
for examination by the exit run 
file. In the primary application 
partition only, a nonzero status 
code causes the content of the type- 
ahead buffer to be discarded and the 
submit or recording file to be 
closed . 


Request Block 


ErrorExit is a system common procedure. 
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Exit 


Description 


The Exit procedure terminates the current 
application system and passes a normal status 
code to the specified exit run file. Exit never 
returns to the calling process. 

Exit is exactly like the ErrorExit operation 
except that the status code in Exit is 
implicit. That is, 

Call Exit 

is equivalent to: 

Call ErrorExit (0) 

Exit : 

1. Terminates the current application system. 

2. Places a normal successful status code (0) in 
the Application System Control Block of the 
application partition. 

3. Closes all files opened for the specific 
application partition except those marked 
long-lived (by the OpenFileLL or 
SetFhLongevity operations; see the "File 
Management" section) . 

4. Invokes the exit run file of the application 
partition . 


Procedural Interface 

Call Exit 


Request Block 


Exit is a system common procedure. 
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Load Task 


Description 


Procedural 


The LoadTask service loads and activates an 

additional task as part of the current 

application system in the application partition. 

LoadTask : 

1. Verifies that the file handle specifies a run 

file that contains a valid task image and 

that the task image fits in the application 
partition memory. 

2. Allocates a short-lived memory segment large 

enough to contain the task image from the 

specified run file. 

3. Reads the task image from the run file into 
the application partition. 

4. Relocates all intersegment references to 

accommodate the memory address at which the 
task image is loaded. 

5. Creates a process to be scheduled at the 

specified priority. The initial values 
loaded into the segment registers (CS, DS, 
SS, ES), the Stack Pointer (SP), and the 
Instruction Pointer (IP) are derived from 
information in the run-file header. 


Interface 

LoadTask (fh, priority, fDebug): ErcType 

where 

fh is the file handle of a run file 

that has been opened by the calling 
process . 

priority is the priority (0-254, with 0 the 

highest) at which to schedule the 
newly created process for 

execution. A value of 255 requests 
that a process not be created. This 
permits the loading of a task image 
that is executed by calling the 
procedures in it from another 
process . 
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fDebug 


indicates whether the task is to be 
debugged. TRUE indicates it is to 
be debugged and therefore not 
scheduled for execution; FALSE 
indicates it is to be scheduled for 
execution. In contrast to its 
meaning in the Chain operation, 
setting fDebug to TRUE does not 
automatically activate the Debugger. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

29 

12 

fh 

2 


14 

priority 

2 


16 

fDebug 

2 
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QueryExitRunFile 

Description 


The QueryExitRunFile service returns the name, 
password, and priority of the exit run file of 
the application partition. 

Procedural Interface 

QueryExitRunFile (pbExitRunFileRet , 

cbExitRunFileRet , 
pbPasswordRet , cbPasswordRet , 
pbPriorityRet ) : ErcType 

pbExitRunFileRet 

cbExitRunFileRet 

define the memory area into which 
the exit run file specification is 
returned. The first byte of the 
returned information is the size of 
the exit run file specification. 


pbPasswordRet 

cbPasswordRet 

define the memory area into which 
the password for the exit run file 
is returned. The first byte of the 
returned information is the size of 
the password. 


pbPriorityRet 

is the memory address of the word 
into which the priority of the exit 
run file is returned. 
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Request. Block 


cbPriorityRet is always 2. 


Offset 

Size 

Field (bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

3 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

187 

12 

reserved 

6 


18 

pbExitRunFileRet 

4 


22 

cbExitRunFileRet 

2 


24 

pbPasswordRet 

4 


28 

cbPas swordRet 

2 


30 

pbPriorityRet 

4 


34 

cbPriorityRet 

2 

2 
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SetExitRunFile 


Description 

The SetExitRunFile service establishes a new exit 

run file for the application partition in which 

the calling process is executing. 

Procedural Interface 

SetExitRunFile (pbExitRunFile , cbExitRunFile , 

pb Pas sword, cbPas sword, 
priority) : ErcType 

where 

pbExitRunFile 

cbExitRunFile 

describe a character string of the 
form {node} [volname] <dirname>f ile- 
name that specifies the run file to 
be loaded into the application 
partition when an Exit request is 
issued by the current task. 

pbPas sword 

cbPassword describe the volume, directory, or 
file password that authorizes access 
to the specified file. 

priority is the priority (10-254, with 10 the 

highest) at which the newly created 
process is scheduled for execution. 
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Request Block 


7-18 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCnt Info 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqcode 

2 

186 

12 

priority 

2 


14 

reserved 

4 


18 

pbExitRunFile 

4 


22 

cbExitRunFile 

2 


24 

pbPas sword 

4 


28 

cb Pas sword 

2 
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8 VIRTUAL CODE SEGMENT MANAGEMENT 


OVERVIEW 


Th e virtual code segment management facility 
permits the execution of application systems that 
exceed the size of physical memory of an 
application partition. This is accomplished 
through the use of the virtual memory technique. 

Virtual code segment management is available to 
the primary or a secondary task of an application 
partition. However, a secondary task cannot be 
virtual if the primary task already uses virtual 
code segment management. 

Primary tasks are those loaded by the Chain, 
ErrorExit, or Exit operations (see the "Task 
Management" section) , or the LoadPrimaryTask 
operation (see the "Application Partition 
Management" section) . 

Secondary tasks are those loaded by the task 
management LoadTask operation. 
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CONCEPTS 


Virtual Memory 


Virtual memory is a technique that makes the 
apparent size of memory of an application 
partition (from the perspective of the 
application programmer) greater than its actual 
physical size. This improves the efficiency of 
memory usage by allowing disk storage, as well as 
the main memory of an application partition, to 
be used to contain parts of the current 
application system. 

Two popular implementations of virtual memory are 
segment swapping and page swap pin g . (The use of 
program overlays is not considered virtual memory 
because it is not transparent to the application 
programmer . ) 


Virtual Code Segment Swapping 

The CTOS Operating System supports virtual code 
segment swapping. Each task is divided into 
variable-length code segments that reside on disk 
in a run file. As the task executes, only those 
code segments that are required at a particular 
time actually reside in the main memory of an 
application partition; the other code segments 
remain on disk until they, in turn, are required. 

When a particular code segment in the memory of 
an application partition is no longer needed, it 
is overlaid by another code segment. This can be 
done because all code segments produced by 
Convergent compilers (and by assembler code that 
is written according to a simple set of 
guidelines; see the Assembly Language Manual ) are 
reentrant . 

When the particular code segment is required 
again, it is simply reread from the run file. 
Since code segments are never modified, they can 
always be read directly from the run file into 
which the Linker wrote them. 


Virtual Code Segment Swapping Versus Page Swapping 

CTOS virtual code segment swapping differs from 
the page swapping of other systems in two 
significant ways: 
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o 


Since only code, not data, segments are moved 
from disk to the main memory of an 
application partition, it is never necessary 
to allocate a swapping file or to write 
segments back to disk. 

o A code segment is a variable-length (up to 
64 k bytes) logical entity, not a fixed-length 
physical entity. A code segment contains one 
or more complete procedures. 

Using the Virtual Code Segment Management Facility 

There are two steps to using virtual code segment 

management : 

o initializing the virtual code segment 
management facility, and 

o specifying to the Linker the desired grouping 
of object modules into code segments. 


Initializing 


The swap buffer is an overlay area in the memory 
of an application partition. It is used to 
contain all nonresident code segments. It must 
be allocated either dynamically using the 
AllocMemorySL operation (see the "Memory 
Management" section) or statically configured 
into the task. The swap buffer is commonly 
allocated dynamically so that its size can be 
determined by the amount of memory available in 
the partition. 

The InitOverlays object module procedure must be 
called before any procedure in a nonresident 
(virtual) code segment is called. 

The arguments to the InitOverlays operation are 
the memory address and the size of the swap 
buffer. This buffer must be large enough to 
contain the largest nonresident code segment. A 
larger buffer permits more code segments to be 
kept in the main memory of an application 
partition and improves system performance. 

After the virtual code segment management 
facility is initialized, no further explicit 
reference must be made to the swap buffer; the 
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facility automatically allocates the memory in 
the swap buffer to code segments as they are read 
in . 


Linking 


When linking a task to use the virtual code 
segment management facility, the desired grouping 
of object modules into code segments must be 
specified to the Linker. 

No restrictions are placed on the ability of 
procedures to call other procedures in any code 
segment to any degree of nesting or recursion. 
Note, however, that the performance of an 
application system is substantially improved if 
some care is exercised in the grouping of 
procedures into object modules and object modules 
into code segments. (See the Linker /Librarian 
Manual for more information about the Linker 
utility. ) 


Using Overlays 


Programs that use overlays have two parts: 
resident and overlaid. 

The resident part contains resident code and 
data. It must contain the main program and the 
call to the InitOverlays operation. 

The overlaid part contains one or more 
overlays . Each overlay corresponds to one or 
more code segments. Only code segments can be 
overlaid. All other segments must remain memory- 
resident . 

The Linker identifies code segments by the class 
name CODE. This is set automatically by FORTRAN 
and Pascal but must be set explicitly when using 
assembly language. 

Normally, a code segment is generated by a single 
compilation and is contained in one object 
module. However, the Linker can combine code 
segments in any number of object modules into a 
single code segment. 
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When using overlays : 

o The maximum size of the overlay area (and 

hence of any overlay) is 64k bytes. 

o The maximum size of the resident code is 64k 
bytes. The data in the resident code does 
not count toward this limit. 

o The maximum number of overlays is 256. 

o Any procedures called before the overlay area 
is initialized must be in the resident code. 

o The SwapAl, SwapO, Swapl, Swap2, and ComSub 

object modules in the CTOS library must be in 
the resident code. 

o All callers of the Lockln and Lockout 
operations in ComSub (for example, SamCop) 
must be in the resident code. 


Virtual Code Segment Management 


8-5 



OPERATIONS : 


PROCEDURES 

Virtual code segment management provides the 
operation listed below. 

InitOverlays initializes the virtual code 

segment management facility. 
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InitOverlays 

Description 

The InitOverlays procedure initializes the 
virtual code segment management facility. 
InitOverlays is called once at the beginning of a 
task. It must be included in the resident code 
of a task and must be called before any procedure 
in a nonresident (virtual) code segment is 
called . 

Procedural Interface 

InitOverlays (pSwapBuffer, 

sSwapBuffer ) : ErcType 

where 

pSwapBuffer is the memory address of the first 
byte of the swap buffer. The buffer 
must be word-aligned. 

sSwapBuffer is the size of the swap buffer. 

This must be a multiple of 512. The 
buffer must be large enough to 
contain the largest nonresident code 
segment. A larger buffer permits 
more nonresident code segments to be 
kept in the main memory of the 
application partition and improves 
system performance. 

Request Block 

InitOverlays is an object module procedure. 
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9 PARAMETER MANAGEMENT 


OVERVIEW 


Forms-Oriented 


Parameters 


The parameter management facility provides a 
structured mechanism for passing limited 
information from one application system to its 
successor within the same partition. 

Application systems that pass parameters include, 
for example, the Convergent Executive in the 
primary application partition, or the batch 
manager in any application partition. 

Interface 

The Convergent Information Processing System 
supports and encourages the use of forms-oriented 
interfaces for workstation operators. — 

The Convergent Executive is an example of a 
forms-oriented interface. The operator types a 
command name and presses the RETURN key; the 
Executive responds with the command form 
appropriate to it. (See the Executive Manual for 
details about this type of interface . ) 

For example, if the operator types Delete and 
presses RETURN, the following form appears: 

Delete 

File list 
[Confirm each?] 


The operator enters data into the fields of the 
form and also corrects typing errors by modifying 
the data. The operator, when satisfied with the 
contents of the fields, presses the GO key. 


Note that the Delete command takes two kinds of 
parameters: a parameter and a list of 
subparameters. A parameter consists of zero or 
more subparameters. A subparameter typically 
consists of an arbitrary sequence of characters 
not including a space. (For Executive 
parameters, see the "Parameters in a Command 
Form" section of the Executive Manual. For batch 
parameters, see the Batch Manual . ) 
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Organizing the Parameters: the Variable-Length Parameter Block 


Continuing the example above, after the operator 
has pressed GO, the Executive organizes the 
operator's data to simplify Delete’s extraction 
of the parameters. The organized data is stored 
in the Variable-Length Parameter Block. 

The Variable-Length Parameter Block (VLPB) is a 
formal structure used by the Executive and batch 
manager to communicate parameters to application 
systems. The VLPB is created in the long-lived 
memory of an application partition, and its 
memory address is stored in the Application 
System Control Block (ASCB) of the application 
partition . 

An ASCB in each application partition 
communicates parameters and other information 
between application systems within its partition. 

The VLPB and the parameter passing services of 
the Executive and batch manager are applicable to 
any application system on a Convergent system. 

A common case is an application system to be 
invoked from the Executive. When implementing 
such an application system, the user decides on a 
command name, the captions for the fields of the 
command form, and the corresponding message that 
appears when the operator presses the HELP key. 
This information is supplied to the Executive 
using the New Command command (as described in 
the Executive Manual ) . 

Another common case is an application system to 
be invoked from the batch manager. When 
implementing such an application system, the user 
creates a batch job control language file (as 
described in the Batch Manual). 
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CONCEPTS 


Parameter and Subparameter 

A parameter consists of zero or more 
subparameters. A subparameter typically consists 
of an arbitrary sequence of characters not 
including a space. For example, the parameter: 

1 abc Work.Fri 

contains three subparameters: 1, abc, and 

Work. Fri . 

A space is embedded in a subparameter by 
including the entire subparameter in single 
quotes. For example, the parameter: 

'1 abc' Work.Fri 

contains two subparameters: 1 abc, and Work.Fri. 


Variable-Length Parameter Block 

The Variable-Length Parameter Block (VLPB) is a 
formal structure used by the Executive or batch 
manager to communicate parameters to application 
systems in an application partition. The VLPB is 
created in the long-lived memory of an 
application partition; its memory address is 
stored in the pVLPB field of the Application 
System Control Block (see below). The 
application system gets its parameters from the 
VLPB using three operations: CParams, 
CSubParams, and RgParam. 

The CParams operation returns the number of 
parameters stored in the VLPB, that is, the 
number of fields in the command form. 

The CSubParams operation returns the number of 
subparameters stored in the VLPB for a specified 
parameter, that is, the number of subparameters 
the operator entered in a specified field of the 
c omma nd f o rm . 

The RgParam operation provides access to the 
parameters stored in the VLPB. 

Four object module procedures support the 
creation of a VLPB: RgParamlnit, RgParamSetElt- 
Next, RgParamSetListStart , and RgParamSetSimple . 
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The VLPB is a self-describing, two-dimensional 
array of character strings. Each element of the 
array rgSdoParam is a pair (ob, cb) of words, 
where ob is the offset within the VLPB of the 
corresponding row of the two-dimensional array, 
and cb is the number of bytes occupied by the 
row. The strings that make up a row are prefixed 
with a 1-byte count and packed together without 
padding . 

The format of the VLPB is shown in Table 9-1 
below. 


Table 9-1. Variable-Length Parameter Block. 

Offset 

Field 

Size 
(bytes ) 

0 

sVarParams 

2 

2 

ibFirstFree 

2 

4 

cParams 

2 

6 

rgSdoParam 
(cParams + 1) 

4* (cParams + 1) 


Application System Control Block 

An Application System Control Block (ASCB) in 
each application partition communicates para- 
meters, the termination code, and other 
information between application systems within 
its partition. 

The address of the ASCB is obtained through the 
GetpASCB operation. 

The format of the ASCB is shown in Table 9-2 
below. 
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Table 9-2. Application System Control Block. (Page 1 of 3) 


Offset. 

0 


2 

6 


7 

8 


Field 

Size 
(bytes ) 

Description 

fhSwapFile 

2 

Set by the Chain op- 
eration. (See the 
"Task Management" 
section.) If the 
primary task is 
virtual, then 
fhSwapFile is the 
file handle of its 
run file; otherwise, 
fhSwapFile is set to 
OFFFFh. 

pVLPB 

4 

Memory address of the 
VLPB in the long- 
lived memory of an 
application 
partition. 

fExecScreen 1 

Set to FALSE by the 
ResetVideo operation 
(see the "Video Dis- 
play Management" 
section) and to TRUE 
by the Executive. If 
fExecScreen is FALSE 
when the Convergent 
Executive is loaded, 
it reinitializes the 
video subsystem. 

fChkBoot 

1 

Set to FALSE during 
CTOS initialization 
and to TRUE by the 
Executive. 

ercRet 

2 

The Chain operation 
writes its ercTermi- 
nation parameter into 
this word. 
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Table 9-2. Application System Control Block. (Page 2 of 3) 


Size 

Offset Field (bytes) Description 


10 pbMsgRet 4 

14 cbMsgRet 2 


pbMsgRet and cbMsgRet 
can be set by an ap- 
plication system to 
describe a string of 
text located in the 
long-lived memory. 
When the Executive is 
loaded, this text 
appears on the video 
display. 


16 reserved 6 


22 fTermination 1 


23 f Vacate 1 


Set to TRUE when a 
user tries to ACTION- 
FINISH an application 
system when ACTION- 
FINISH is disabled; or 


when an application 
system tries to 
terminate the task in 
a locked secondary 
partition. This is 
set to FALSE when a 
task replaces the old 
task in the partition. 


Set to TRUE when a 
user or an application 
system tries to vacate 
the task in a locked 


secondary partition. 
This is set to FALSE 
when a task replaces 
the old task in the 
partition. 
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Table 9-2. Application System Control Block. (Page 3 of 3) 


Offset Field 


Size 

(bytes) Description 


oLastTask 


fExecFont 


bActionCode 1 


cParMemArray 2 


Offset of the last 
task loaded. 

Set to FALSE by the 
Operating System when 
the font is changed. 
When the Executive 
finds fExecFont set to 
FALSE, it reloads the 
font and sets 
fExecFont to TRUE. 

Contains the last 
action code detected 
by the keyboard 
process (not including 
ACTION- A, B, and 
FINISH codes). 

The size of the memory 
array (in 16-byte 
paragraphs ) of the 
primary task when 
loaded . 


reserved 


sbUserName 


sbPassword 


sbCmdFile 


The name of the 
current user (the 
first byte of the 
string is the length 
of the name) . 

The password the user 
gave when signing on 
(for accessing the 
user configuration 
file) . 

The name of the 
user's Executive 
command file. 
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OPERATIONS : PROCEDURES 


Parameter management operations are categorized 
by function in Table 9-3 below. 


Table 9-3. Parameter Management Operations by Function. 

Retrieval 

Creation 

CParams 

RgParamlnit 

CSubParams 

RgParamSetEltNext 

GetpASCB 

RgParamSetListStart 

RgParam 

RgParamSetSimple 


Retrieval 


CParams 

CSubParams 

GetpASCB 

RgParam 

Creation 

RgParamlnit 


returns the number of 
parameters stored in the 
Variable-Length Parameter 
Block . 

returns the number of 
subparameters stored in the 
Variable-Length Parameter Block 
for a specified parameter. 

returns the address of the 
Application System Control 
Block in an application 
partition. 

provides access to the 
parameters stored in the 
Variable-Length Parameter 
Block. 


initializes the specified 
memory to be the Variable- 
Length Parameter Block. 


RgParamSetEltNext 

creates an additional 
subparameter of the current 
parameter in the Variable- 
Length Parameter Block. 
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RgParamSe tLi stStart 

initiates the creation of a 
parameter with multiple 
subparameters . 

RgParamSetSimple creates a parameter with one 

subparameter . 
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CParams 


Description 

The CParams procedure returns the number of 
parameters stored in the Variable-Length 
Parameter Block, that is, the number of fields in 
the command form. 

Note that the Convergent Executive passes the 
name of the command as parameter zero. 

Procedural Interface 

CParams: WORD 

Request Block 

CParams is an object module procedure. 
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CSubParams 


Description 


The CSubParams procedure returns the number of 
subparameters stored in the Variable-Length 
Parameter Block for a specified parameter, that 
is, the number of subparameters the operator 
entered in a specified field of the form. 

Procedural Interface 

CSubParams (iParam): WORD 

where 

iParam is the index of the parameter. 


Request Block 


CSubParams is an object module procedure. 
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GetpASCB 

Description 


The GetpASCB procedure returns the address of the 
Application System Control Block (ASCB) of the 
application partition in which the application 
system is executing. 

Procedural Interface 

GetpASCB (ppASCBRe t ) : ErcType 

where 

ppASCBRet is the memory address of a pointer 
that is returned with the address to 
the ASCB. 

Request Block 

GetpASCB is a system common procedure. 
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RgParam 

Description 

The RgParam procedure provides access to the 
parameters stored in the Variable-Length 
Parameter Block. Each RgParam invocation returns 
the memory address and size of a subparameter. 
Note that the Executive stores the command name 
used to invoke the application system in RgParam 
( 0 , 0 ). 

Procedural Interface 

RgParam (iParam, jParam, pSdRet) : ErcType 
where 

iParam is the index of the parameter. 

jParam is the index of the subparameter. 

pSdRet is the location of a 6-byte block of 

memory. The memory address of the 
subparameter is returned in the 
first 4 bytes, and its size is 
stored in the last 2 bytes. 

Request Block 

RgParam is an object module procedure. 
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RgParamlnit 

Description 

The RgParamlnit procedure initializes the 
specified memory to be the Variable-Length 
Parameter Block. If the block of memory is not 
large enough, RgParamlnit attempts to increase 
its size by allocating additional long-lived 
memory. This attempt succeeds only if the block 
of memory is at the top of the long-lived memory 
of an application partition. 

Procedural Interface 

RgParamlnit (pVarParams, sVarParams, 
iParamMax): ErcType 

where 

pVarParams 

sVarParams describe the block of memory to be 
used for the Variable-Length 
Parameter Block. If sVarParams is 
0, the current Variable-Length 
Parameter Block is reinitialized. 

iParamMax is one less than the number of 
parameters to be recorded. 

Request Block 

RgParamlnit is an object module procedure. 
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RgParamSetEltNext 

Description 


The RgParamSetEltNext procedure creates an 
additional subparameter of the current parameter 
in the Variable-Length Parameter Block. The 
invocation of RgParamSetEltNext must immediately 
follow the invocation of either the RgParamSet- 
ListStart or RgParamSetEltNext procedure. 

If the Variable-Length Parameter Block is not 
large enough to accommodate this subparameter, it 
is compacted and an attempt made to extend it by 
allocating additional long-lived memory. This 
attempt succeeds only if the Variable-Length 
Parameter Block is at the top of the long-lived 
memory of an application partition. 

Procedural Interface 

RgParamSetEltNext (pSd): ErcType 
where 

pSd is the location of a 6-byte block of 

memory, the first 4 bytes of which 
contain the memory address of the 
string to be used and the last 2 
bytes of which contain the string's 
length . 


Request Block 


RgParamSetEltNext is an object module procedure. 
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RgParamSetListStart 

Description 


The RgParamSetListStart procedure initiates the 
creation of a parameter with multiple 
subparameters. The RgParamSetEltNext procedure, 
which must be called immediately following an 
invocation of RgParamSetListStart, creates a 
subparameter. If the parameter already exists, 
all its old subparameters are destroyed and the 
memory they occupied reused. 

Procedural Interface 

RgParamSetListStart (iParam): ErcType 
where 

iParam is the index of the parameter. 

Request Block 


RgParamSetListStart is an object module 
procedure . 
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RgParamSetSimple 

Description 

The RgParamSetSimple procedure creates a 
parameter with one subparameter. If the 

parameter already exists, all its old 
subparameters are destroyed and the memory they 
occupied reused. 

If the Variable-Length Parameter Block is not 
large enough to accommodate this parameter, it is 
compacted and an attempt made to extend it by 
allocating additional long-lived memory. This 
attempt succeeds only if the Variable-Length 
Parameter Block is at the top of the long-lived 
memory of an application partition. 

Procedural Interface 

RgParamSetSimple (iParam, pSd): ErcType 

where 

iParam is the index of the parameter. 

pSd is the location of a 6-byte block of 

memory, the first 4 bytes of which 
contain the memory address of the 
string to be used and the last 2 
bytes of which contain the string's 
length . 

Request Block 

RgParamSetSimple is an object module procedure. 
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10 APPLICATION PARTITION MANAGEMENT 


OVERVIEW 


The application partition management facility 
supports the simultaneous execution of several 
application systems, each in its own partition. 
An interactive application system can be 
executing in one partition while noninteractive 
application systems are executing in other 
partitions . 

Each application system can load and activate any 
number of tasks within its partition. Any number 
of processes can execute the code in each task. 
Each application system is completely independent 
of the others, yet can communicate with 
application systems in other partitions. 
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CONCEPTS 


Types of Partitions 

The memory of a system consists of two types of 
partitions : 

o system partitions, which are loaded with the 
operating system (OS) and dynamically 
installed system services, and 

o application partitions, each of which can be 
loaded with an application system. 

When a system is initialized, the OS is loaded 
into the system partition at the low-address end 
of memory. Dynamically installed system services 
are loaded into an extended system partition 
located at the high-address end of memory. All 
remaining memory is defined as a single 
application partition called the primary 
application partition. (See Figure 10-1 below.) 

When new partitions are created, they are placed 
at the high-address end of the existing 
application partition and are called secondary 
application partitions. The remaining memory is 
defined as the primary application partition. 
(See Figure 10-2 below.) 


Types of Application Partitions 

Primary Application Partition 

The primary application partition is for 
interactive programs that use the keyboard and 
video display to interact with the user. Such 
partitions can be loaded with interactive 
programs chosen by the user, such as the Editor, 
Word Processor, or Terminal Emulators. 

Secondary Application Partitions 

Secondary application partitions are for 
noninteractive applications. Such partitions can 
be loaded with user applications, the batch 
manager, and system services (such as the printer 
spooler, ISAM, or a remote job entry). 
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Application systems executing in secondary 
application partitions under control of the batch 
manager have their keyboard input and video 
output automatically redirected to System Input 
(Sysln) and System Output (SysOut) facilities. 


Low End of Memory 





System Partition 







Interactive 

Application H 

System 


Primary Application Partition 


High End of Memory 


Extended System Partition 






Figure 10-1. Memory Organization without Secondary Application Partitions. 


Dynamic Control of Application Partitions 

Application partitions are dynamically controlled 
through utilities (described in the System 
Utilities Manual ) or operations (describid In 
this Manuaiy^ 
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The operations described in this section control 
processing in secondary application partitions. 
Operations described elsewhere in this Manual 
apply to all application partitions, unless 
otherwise noted. 



Low End of Memory 


Interactive 

Application 

System 


Noninteractive 

Application 

Systems 


High End of Memory 



System Partition 


Primary Application Partition 



Secondary Application Partition B 


Figure 10-2. Memory Organization with Secondary Application Partitions. 


Memory Organization of Application Partitions 

The memory of application partitions is organized 
as shown in Figure 10-3 below. The entities in 
the partition are: 
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o system data structures describing the 
partition and its current application system, 
and 

o primary and secondary tasks that make up the 
current application system. 

A process executing in an application partition 
can allocate and deallocate the memory of its own 
partition. Long-lived memory is allocated from 
the low-address end, and short-lived memory from 
the high-address end of the partition. A process 
cannot allocate or deallocate memory in other 
partitions . 


Low End of Memory 


High End of Memory 


System Data Structures 


Long-Lived Memory 


Common Pool of Unallocated Memory 


Short-Lived Memory 


Secondary Task 2 
Secondary Task 1 
Primary Task 


Figure 10-3. Memory Organization of an Application Partition. 
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Creating Secondary Application Partitions 


Secondary application partitions can be created 
and loaded either at system initialization or 
dynamically during execution. 


At System Initialization 

A user can create and load secondary application 
partitions through a batch job control file that 
is processed during system initialization. 
System services such as the printer spooler, 
ISAM, or RJE can be loaded in this way. (See the 
Batch Manual . ) 


Dynamically 


A process residing in the primary application 
partition can create secondary application 
partitions dynamically with the CreatePartition 
operation. Each new partition is created from 
the high-address end of the primary application 
partition. The remaining memory is redefined as 
the primary application partition. Create- 
Partition specifies a partition name, returns a 
partition handle, and causes the exit run file 
(see below) to be loaded immediately into the 
primary application partition, replacing the 
application system that executed the operation. 


Partition Handle 


A partition handle is a 16-bit integer that 
uniquely identifies a secondary application 
partition. It is returned by the CreatePartition 
operation and is used to refer to the partition 
in subsequent operations such as GetPartition- 
Status, LoadPrimaryTask, and RemovePartition . 

A process can obtain a previously assigned 
partition handle by supplying the partition name 
when using a GetPartitionHandle operation. 


Loading Tasks 


A secondary application partition is vacant when 
created. A process in the primary application 
partition loads and activates the first task, 
called the primary task, in a secondary 
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application partition with the LoadPrimaryTask 
operation . 

The primary task in turn can load additional 
tasks, called secondary tasks, in its own 
partition with the LoadTask operation. (See the 
"Task Management" section.) 


Exit Run File 


An exit run file is a user-specified file that is 
loaded and activated when the executing 
application system exits. Each application 
partition has its own exit run file. (See the 
"Task Management" section.) 

In the primary application partition, if no exit 
run file is specified, the system will 
malfunction and reboot itself. If the exit run 
file cannot be read, it displays the message 
"Cannot load exit run file" and a status code 
indicating the type of error that occurred. If 
the exit run file is on a floppy disk, the user 
can insert a floppy disk with the appropriate 
exit run file and the system will resume loading 
of the exit run file. 

In a secondary application partition, if no exit 
run file is specified or if it cannot be read, 
the partition becomes vacant. 


Obtaining Partition Status 

A process can obtain status information about a 
specified application partition and the job 
executing in it with the GetPartitionStatus 
operation. The process can obtain any of the 
following: User Control Block, Partition 
Descriptor, or Batch Control Block. (See "System 
Data Structures" below.) 


Interpartition Communication 

A process in one application partition can send 
messages to a process in another application 
partition. The destination process first 
allocates an exchange and makes the exchange 
known to the OS with the SetPartitionExchange 
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operation. The sender process obtains the 
exchange number with the GetPartitionExchange 
operation, then sends messages to the exchange. 

The processes engaged in the interpartition 
communications must lock themselves into their 
respective partitions with the SetPartitionLock 
operation to avoid being terminated by a 
TerminatePartitionTasks or VacatePartition 
operation from the primary application 
partition. The termination of an application 
system that is currently engaged in 
interpartition communication will result in 
unpredictable system malfunction. 


Terminating Tasks 

A process terminates the entire application 
system in its own partition by using the Chain, 
Exit, or ErrorExit operation. (See the "Task 
Management" section. 

In addition, two operations can be executed in 
the primary application partition to terminate 

the application system in a specified secondary 
application partition: 

o TerminatePartitionTasks terminates all tasks 

in the specified secondary application 
partition and loads and activates the 
partition's exit run file, if one is 
specified . 

o VacatePartition terminates all tasks in the 
specified secondary application partition but 
does not load and activate the partition's 
exit run file. VacatePartition leaves the 
partition vacant. 


Removing Partitions 

A process in the primary application partition 
can remove an existing secondary application 
partition that is vacant with the RemovePartition 
operation . 

A secondary application partition is vacant when: 
o it is first created. 
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o the current application system exits with no 
exit run file specified, or 

o the VacatePartition operation is performed. 

If a secondary application partition adjacent to 
the primary application partition is removed, the 
memory it occupied becomes part of the primary 
application partition. 

If a secondary application partition that is not 
adjacent to the primary partition is removed, the 
memory it occupied becomes a block of unused 
memory. Adjacent blocks of unused memory are 
combined into a single block. Such blocks serve 
as a pool of unallocated memory from which new 
application partitions are created using a first- 
fit algorithm. 


Deallocation of System Resources 

In a compact system, all allocated resources are 
deallocated when the application system exits. 
(Examples of allocated resources are exchanges, 
file handles, and timer requests.) 

In a system where multiple application systems 
can be executed simultaneously, only the 
resources allocated to an exiting application 
system are deallocated. Information on the 
resource allocations of each application system 
is stored in application partition data 
structures that augment but do not replace the 
data structures present in the compact 
configuration. 


Application Partition Data Structures 

The application partition management facility 
maintains six data structures for each 
application partition. These data structures are 
described in the order shown in Figure 10-4 (from 
the left side, top to bottom) : 

o Extended User Control Block (Extended UCB) , 
which contains the offset of the Partition 
Descriptor . 

o Partition Descriptor, which contains the 
partition name, and the boundaries of the 
partition and of its long- and short-lived 
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memory areas. It also contains internal 
links to partition descriptors in other 
partitions . 



111 1 " 

UCB 



Partition Configuration Block 


Extended UCB 



Extended Partition Descriptor 



Batch Control Block 



Application System Control Block 

L-*. 




Long-Lived Memory 


Partition Descriptor 



Common Pool of Unallocated Memory 




Short-Lived Memory 


Secondary Task 2 
Secondary Task 1 
Primary Task 


Figure 10-4. Application Partition Data Structures. 


Partition Configuration Block, which contains 
the offsets of the Extended partition 
Descriptor, Batch Control Block, and 
Application System Control Block. 

Extended Partition Descriptor, which contains 
specifications for the current application 
system and exit run file. 
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o 


Batch Control Block, which contains the job 
name and class, file handle and logical file 
address of the batch job control file. 
Assigned Device Block, and Sysln and SysOut 
byte stream work area and buffers. This data 
structure is used by the batch manager. 

o Application System Control Block (see the 
"Parameter Management" section), which 
communicates parameters between application 
systems . 

The format for each data structure is given in 
Appendix E. 
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OPERATIONS : SERVICES 


Application partition management operations are 
categorized by function in Table 10-1 below. 


Table 10-1. Application Partition Management Operations by Function. 


Interpartition 

Communication 

Get Part itionEx change 
SetPartitionExchange 
SetPartitionLock 


Partition Control 

CreatePartition 
GetPartitionHandle 
GetPartitionStatus 
RemovePart i t ion 


Task Control 

LoadPrimaryTask 

TerminatePartitionTasks 

VacatePartition 


Interpartition Communication 

GetPartitionExchange 

gets the exchange number set up 
by the SetPartitionExchange 
operation . 

SetPartitionExchange 

sets up an exchange number that 
can be queried by a task in 
another application partition 
for interpartition 
communication . 

SetPartitionLock declares whether an application 

system in the specified 
application partition can be 
terminated by the Terminate- 
PartitionTasks or Vacate- 
Partition operation. 
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Partition Control 


CreatePartition creates a new secondary 

application partition, assigns 
its name, and returns a 
partition handle. 

GetPartitionHandle 

translates the name of the 
specified application partition 
into a partition handle. 

GetPartitionStatus 

returns status information 
about the specified application 
partition and the job currently 
executing in it. 

RemovePartition removes the specified vacant 

application partition. 

Task Control 

LoadPrimaryTask loads and activates a primary 

task run file in the vacant 
application partition specified 
by the partition handle. 

TerminatePartitionTasks 

terminates all tasks in the 
application partition specified 
by the partition handle and 
loads the partition's exit run 
file . 

VacatePartition terminates all tasks in the 

application partition specified 
by the partition handle but 
does not load the partition's 
exit run file. VacatePartition 
leaves the partition vacant. 
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CreatePartition 


Description 


The CreatePartition service creates a new 

application partition, assigns its name, and 
returns a partition handle. CreatePartition can 
be issued only by a process executing in the 
primary application partition. 

CreatePartition causes the exit run file to be 
loaded into the primary application partition, 
replacing the application system that executed 
the CreatePartition operation. 

Procedural Interface 

CreatePartition ( pbPartitionName , 

cbPartitionName, cParagraph, 
fRunBatch, pPhRet): ErcType 

where 

pbPartitionName 

cbPartitionName 

describe the partition name (up to 
12 characters) . 

cParagraph is the number of paragraphs of 
memory to be allocated to the 
application partition. 

fRunBatch is TRUE or FALSE. TRUE indicates a 
Batch Control Block of 1.3 kilobytes 
is allocated in addition to the 
memory for the partition itself. 
FALSE indicates no Batch Control 
Block is allocated. 

pPhRet is the memory address of the word 

into which the partition handle is 
returned . 
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Request Block 


sPhRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

181 

12 

cParagraph 

2 


14 

fRunBatch 

1 


15 

reserved 

3 


18 

pbPartitionName 

4 


22 

cbPartitionName 

2 


24 

pPhRet 

4 


28 

sPhRet 

2 

2 
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GetPartitionExchange 

Description 


The GetPartitionExchange service returns the 
exchange number established by the SetPartition- 
Exchange operation. The exchange number is used 
to communicate with an application system 
executing in another application partition. 

Procedural Interface 

GetPartitionExchange (ph, pExchRet) : ErcType 
where 

ph is the partition handle returned 

from a CreatePartition or 

GetPartitionHandle operation. A 0 
specifies the application partition 
in which the client process is 
executing . 

pExchRet is a pointer to a 16-bit word into 

which the exchange is returned. 


Request Block 


sExchRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

184 

12 

ph 

2 


14 

pExchRet 

4 


16 

sExchRet 

2 

2 
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GetPartitionHandle 


Description 


The GetPartitionHandle service translates the 
specified application partition name into a 
partition handle. 

Procedural Interface 

GetPartitionHandle (pbPartitionName , 

cbPartitionName , 
pPhRet): ErcType 


where 

pbPartitionName 

cbPartitionName 

describe the partition name (up to 
12 characters). 

pPhRet is the memory address of the word 

into which the partition handle is 
returned . 


Request Block 


sPhRet is always 2. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

177 

12 

pbPartitionName 

4 


16 

cbPartitionName 

2 


18 

pPhRet 

4 


22 

sPhRet 

2 

2 
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GetPartitionStatus 


Description 


The GetPartitionStatus service returns status 
information about the specified application 
partition and the job currently executing in it. 

Procedural Interface 

GetPartitionStatus (ph, statusCode, pStatusRet, 

sStatusMax): ErcType 


where 

ph is the partition handle returned 

from a CreatePartition or 

GetPartitionHandle operation. A 0 
specifies the application partition 
in which the client process is 
executing . 


statusCode specifies the status code. The 
status items and values are : 

Code Item Size 


0 Partition Descriptor 33 

1 Extended Partition 

Descriptor 172 

2 Batch Control Block 1548 

3 Application System 

Control Block 280 


pStatusRet 

sStatusMax describe the memory area to which 
the status information is returned. 
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Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

185 

12 

ph 

2 


14 

statusCode 

2 


16 

pStatusRet 

4 


20 

sStatusMax 

2 
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LoadPrimaryTask 

Description 


The LoadPrimaryTask service loads and activates 
the primary task run file in the vacant 
application partition specified by the file 
specification. 

LoadPrimaryTask : 

1. Verifies that the file specification 
specifies a run file that contains a valid 
task image and that the task image fits in 
the application partition. 

2. Allocates a short-lived memory segment large 
enough to contain the task image from the 
specified run file. 

3. Reads the task image from the run file into 
the application partition. 

4. Relocates all intersegment references to 
accommodate the memory address at which the 
task image is loaded. 

5. Creates a process to be scheduled at the 

specified priority. The initial values 

loaded into the segment registers (CS, DS, 
SS, ES) , the Stack Pointer (SP), and the 
Instruction Pointer (IP) are derived from 
information in the run-file header. (See the 
"Task Management" section.) 


Procedural Interface 

LoadPrimaryTask (ph, pbFileSpec, cbFileSpec, 

pbPas sWord, cbPas sWord, 
priority) : ErcType 

where 

ph is the partition handle returned 

from a CreatePartition or 

GetPartitionHandle operation. 

pbFileSpec 

cbFileSpec describes a character string of the 
form {node} [volname] <dirname> file- 
name . The distinction between 
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uppercase and lowercase in file 
specifications is not significant in 
matching file names. 


pbPas sWord 

cbPassWord describes the volume, directory, or 
file password that authorizes access 
to the specified file. 

priority is the priority (0-254, with 0 the 

highest) at which to schedule the 
newly created process for 
execution. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

178 

12 

ph 

2 


14 

priority 

2 


16 

reserved 

2 


18 

pbFileSpec 

4 


22 

cbFileSpec 

2 


24 

pbPas sWord 

4 


28 

cbPassWord 

2 
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ReraovePar t it ion 


Description 


The RemovePartition service removes the specified 
vacant application partition. RemovePartition 
can be issued only from a process executing in 
the primary application partition. 

Procedural Interface 

RemovePartition (ph) : ErcType 
where 

ph is the partition handle returned from a 

CreatePartition or GetPartitionHandle 
operation. A 0 specifies the applica- 
tion partition in which the client 
process is executing. 

Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

176 

12 

ph 

2 
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SetPartitionExchange 

Description 


The SetPartitionExchange service sets up an 
exchange number that can be queried by a task in 
another application partition for interpartition 
communication. The application system should use 
the SetPartitionLock operation before using 
SetPartitionExchange to ensure the integrity of 
its operation. 

Procedural Interface 

SetPartitionExchange (exchange): ErcType 

exchange is an exchange previously allocated 

by the application system. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

183 

12 

exchange 

2 
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SetPartitionLock 


Description 


The SetPartitionLock service declares whether an 
application system executing in the specified 
application partition is locked. If it is 
locked, it cannot be terminated by the 
TerminatePartitionTasks or VacatePartition opera- 
tion. An application system can lock itself into 
its own partition only. 

An Exit or ErrorExit from an application system 
in the locked partition vacates the application 
partition, but no other run file is loaded and 
the partition cannot be deleted except by system 
reload . 

Procedural Interface 

SetPartitionLock: (fLock) ErcType 

where 

fLock is TRUE or FALSE. TRUE means that 

the partition is locked. FALSE 
means that the partition is 
unlocked . 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCnt Info 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

182 

12 

fLock 

1 


13 

reserved 
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TerminatePartitionTasks 

Description 

The TerminatePartitionTasks service terminates 
all tasks in the application partition specified 
by the partition handle and loads and activates 
the partition's exit run file. 

If the partition is locked, a status code is 
returned and a flag is set in the Application 
System Control Block to notify the task in the 
partition. 

Procedural Interface 

TerminatePartitionTasks (ph) : ErcType 
where 

Ph is the partition handle returned 

from a CreatePartition or 
GetPartitionHandle operation. 

Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

179 

12 

Ph 

2 
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VacatePart.it ion 


Description 


The VacatePartition service terminates all tasks 
in the application partition specified by the 
partition handle but does not load and activate 
the exit run file. VacatePartition leaves the 
partition vacant. 

If the partition is locked, a status code is 
returned and a flag is set in the Application 
System Control Block to notify the task in the 
partition. 

Procedural Interface 

VacatePartition (ph) : ErcType 
where 

ph is the partition handle returned 

from a CreatePartition or 

GetPartitionHandle operation. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

180 

12 

ph 

2 
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11 CLUSTER MANAGEMENT 


OVERVIEW 


One high-speed RS-422 channel is standard on each 
workstation. In small cluster configurations (up 
to four cluster workstations), the master 
workstation uses this Channel for communications 
with the cluster workstations. However, in large 
cluster configurations, the master IWS 
workstation uses one or two Communications I/O 
Processors (CommlOPs) for communications with the 
cluster workstations. 

The CommlOP , which is added to the Multibus of 
the master IWS workstation, is an intelligent 
communications processor based on the Intel 8085 
microprocessor. The CommlOP serves up to four 
cluster workstations on each of its two high- 
speed serial input/output channels. (The CommlOP 
can actually handle up to 15 cluster workstations 
per high-speed line if they have their own local 
file system and only occasionally access files on 
the master workstation.) 

CommlOP software consists of an 8085 bootstrap- 
ROM program, the main CommlOP program (which 
executes in 8085 RAM) , and a CommlOP handler 
(written in 8086 code) which executes in system 
memory under CTOS control. 


Cluster Management 


11-1 



CONCEPTS 


The CommlOP is an intelligent communications 
processor based on the Intel 8085 micro- 
processor. The CommlOP serves up to four cluster 
workstations (CWS) on each of its two high-speed 
serial input/output (SIO) channels. 


Software 


CommlOP software consists of: 

o the 8085 bootstrap-ROM program (used for 

self-tests) , 

o the main CommlOP program (which executes in 
8085 RAM) , and 

o the CommlOP handler (written in 8086 code) 

which executes in system memory under CTOS 
control . 


Initialization 


The CommlOP and the IWS master workstation 
communicate using interprocessor interrupts and 
shared memory. When the master workstation is 
turned on or its reset button pushed, the CommlOP 
performs a self-test using the 8085 bootstrap-ROM 
program and waits for an interrupt from the 8086 
processor . 

The CommlOP handler initializes each CommlOP in 
four steps. (The number of CommlOPs is a system 
build parameter.) The CommlOP: 


1. 

acknowledges to the CommlOP handler 
is functioning. 

that 

it 

2. 

runs a memory test in its RAM, 



3. 

loads the main CommlOP program into 
from system memory, and 

its 

RAM 

4. 

starts operation. 




The CommlOP and the CommlOP handler communicate 
using an initialization control block located in 
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system memory at locations OlEOh-OlEFh. The 
CommlOP acknowledges completion of each of the 
above steps by writing a completion status in the 
initialization control block. 

The CommlOP can also, as part of its 
initialization, (1) dump the contents of its RAM 
into system memory (this is useful for 
debugging), and (2) test system memory. These 
two functions are system build parameters and 
occur, if requested, after steps 1 and 2 above, 
respectively . 


Operation 


Before the main CommlOP program actually starts 
operation, the CommlOP handler establishes queues 
in system memory for its use. These queues 
contain addresses of buffers used by the CommlOP 
to copy requests from each CWS. 

As a request comes in from the CWS, the main 
CommlOP program obtains a buffer, copies the 
request into it, and places the request on the 
inbound request queue . The CommlOP handler 
removes the request from the inbound request 
queue and submits it to the master workstation 
Agent Service Process, which then submits it to 
the appropriate system service process. 

After the request is processed, it is returned to 
the CommlOP handler, which places it on the 
outbound data queue. The CommlOP then copies the 
request into its own RAM and returns the response 
to the appropriate CWS. 

The CommlOP interrupts the master workstation 
only when it deposits data onto a previously 
empty queue. The Communications Interrupt 
Service Routine in the 8086 processor sends a 
message to the exchange of the CommlOP handler to 
awaken it . 

The maximum number of requests a CWS can have 
outstanding is three. 


Status 


At regular intervals, the CommlOP updates a 
status block in system memory. The CommlOP 
inserts a status code into this block if it 
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detects any irrecoverable errors (such as 
hardware malfunction and invalid control 
structures) . The content of the status block is 
returned by the GetClusterStatus operation. 

The master workstation (with or without a 
CommlOP) keeps statistics about errors and normal 
operational parameters. The GetClusterStatus 
operation makes these statistics available to any 
workstation . 
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OPERATIONS s SERVICES 


Cluster management provides the operations listed 

below. 

DisableCluster allows an application system on 

the master workstation to 
disable polling of the CWSs 
after a specified time 
period. DisableCluster is also 
used to resume polling of the 
CWSs. 

GetClusterStatus returns usage statistics for 

each communications channel and 
the workstations attached to 
it. 

GetWSUserName returns the user name that is 

signed on at the specified CWS. 

SetWSUserName stores the user signon name of 

the workstation. 
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DisableCluster 


Description 


The DisableCluster service allows an application 
system on the master workstation to disable 
polling of the cluster workstations after a 
specified time period. DisableCluster is also 
used to resume polling of the CWSs. 

During the specified time period, the GetDateTime 
operation (see the "Timer Management" section) 
returns the "Master workstation going down" 
status code and the time left (in seconds) before 
polling stops. After the specified time period, 
all operations return status code 46 ("Master 
workstation going down"). 

Typically, the application system (for example, 
the Convergent Executive in the primary 
application partition) on the CWS that performs 
the GetDateTime operation would notify the CWS 
user when it received the "Master workstation 
going down" status code. 

DisableCluster is useful for stopping all CWS 
activity, for example, to perform software 
maintenance on the master workstation. 

Procedural Interface 

DisableCluster ( fDisablePoll, 

timelnterval): ErcType 

where 

fDisablePoll 

disables polling if TRUE or resumes 
it if FALSE. 


timelnterval 

is the time period (in tenths of a 
second). This is not meaningful if 
fDisablePoll is FALSE. 
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OPERATIONS : SERVICES 


Cluster management provides the operations listed 
below. 

DisableCluster allows an application system on 

the master workstation to 
disable polling of the CWSs 
after a specified time 
period. DisableCluster is also 
used to resume polling of the 
CWSs . 

GetClusterStatus returns usage statistics for 

each communications channel and 
the workstations attached to 
it . 
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DisableCluster 


Description 


The DisableCluster service allows an application 
system on the master workstation to disable 
polling of the cluster workstations after a 
specified time period. DisableCluster is also 
used to resume polling of the CWSs. 

During the specified time period, the GetDateTime 
operation (see the "Timer Management" section) 
returns the "Master workstation going down" 
status code and the time left (in seconds) before 
polling stops. After the specified time period, 
all operations return status code 46 ("Master 
workstation going down"). 

Typically, the application system (for example, 
the Convergent Executive in the primary 
application partition) on the CWS that performs 
the GetDateTime operation would notify the CWS 
user when it received the "Master workstation 
going down" status code. 

DisableCluster is useful for stopping all CWS 
activity, for example, to perform software 
maintenance on the master workstation. 

Procedural Interface 

DisableCluster ( fDisablePoll , 

timelnterval ) : ErcType 

where 

fDisablePoll 

disables polling if TRUE or resumes 
it if FALSE. 


timelnterval 

is the time period (in tenths of a 
second). This is not meaningful if 
fDisablePoll is FALSE. 
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Request Block 



Cluster Management 


^oo 



GetClusterStatus 

Description 


The GetClusterStatus service returns usage 
statistics for each communications line and the 
workstations attached to it. 

The communications channels are identified as 
follows : 


Channel Number Communications Channel 


0 

1 

2 

3 

4 


standard channel 
CommlOP 1, Channel A 
CommlOP 1, Channel B 
CommlOP 2, Channel A 
CommlOP 2, Channel B 


Procedural Interface 

GetClusterStatus (iLine, pBufferRet, 

sBufferMax): ErcType 

where 

iLine is the communications channel 

number . 


pBufferRet is the memory address of the buffer 
into which to place the communica- 
tions status buffer (see Table 11-1, 
below) . 

sBufferMax is the size of the buffer. If the 
buffer is too small, the statistics 
are truncated. 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

100 

12 

iLine 

2 


14 

reserved 

4 


18 

pBuf ferRet 

4 


22 

sBuf ferMax 

2 




Table 11-1. Communications Status Buffer. 

Offset 

Field 

Size 
(bytes ) 

0 

nWsConf 

1 

1 

nWsActive 

1 

2 

Up 

4 

6 

Idle 

4 

10 

Ops 

4 

14 

ErrTO 

4 

18 

ErrCRC 

4 

22 

ErrOvrn 

4 

26 

ErrGen 

4 

30 

rgWsStatus 

n*16 


where 

nWsConf is the number of workstations 

configured for this communications 
channel at system build . 

nWsActive is the number of workstations 

currently active. 
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up 


Idle 


Ops 


ErrTO 


is the number of 100 ms intervals 
elapsed since the communications 
channel was activated. 

is the number of 100 ms intervals 
elapsed in which the communications 
channel was inactive. 

is the number of operations 
performed on this communications 
channel . 

is the number of time out errors. 


ErrCRC 


is the number of cyclic redundancy 
check errors . 


ErrOvrn 


is the number of overrun errors. 


ErrGen 


is the number of sequence and other 
nonclassified errors. 


rgWsStatus is an array of n_ workstation status 
blocks, where n_ is the number of 
configured workstations. The format 
of each block is shown in Table 11-2 
below . 



Table 11-2. wsStatus Block. 


Offset 

Field 

Size 
(bytes ) 

0 

iUserNum 

1 

1 

f Active 

1 

2 

RxRq 

4 

6 

nRqs 

2 

8 

reserved 

8 


where 

iUserNum is the user number associated with 

the workstation. 

f Active is the workstation active flag. The 

workstation is inactive if it is 0, 
and active if it is OFFh . 
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RxRq 


nRqs 


is the number of requests received 
during the current session for the 
workstation. 

is the number of pending requests 
for this workstation. 
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GetWSUse rName 


Description 

The GetWSUserName service returns the user name 
that is signed on at the specified CWS. It is 
used with the GetClusterStatus operation to find 
the user names of active workstations (see the 
description of the GetClusterStatus operation 
above ) . 

Procedural Interface 

GetWSUserName (WSNum, pWSUserNameRet, 

sWSUserNameRetMax) : ErcType 

where 

WSNum is the workstation identification 

number . 

pWSUserNameRet 

is the memory address of the first 
byte of the buffer to which the user 
name is returned. The first byte of 
the character string is the size 
(maximum of 31). 

sWSUserNameRetMax 

is the size of the buffer. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

202 

12 

WSNum 

2 


14 

reserved 

4 


18 

pWSUserNameRet 4 


22 

sWSUserNameRetMax 2 
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SetWSUserName 


Description 

The SetWSUserName service stores the user signon 
name of the workstation. SetWSUserName is used 
primarily by the Signon program which also places 
the user name in the Application System Control 
Block of the master workstation in a cluster 
configuration (see the System Programmer ' s Guide 
and the "Application System Control Block" 
subsection in the "Parameter Management" section 
above) . 

Procedural Interface 

SetWSUserName (pbUserName, cbUserName) : ErcType 
where 

pbUsername 

cbUserName describe the user signon name to be 
stored. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

203 

12 

reserved 

6 


18 

pbUserName 

4 


22 

cbUserName 

2 
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12 NETWORK MANAGEMENT 

(To be supplied) 
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13 SYSTEM SERVICES MANAGEMENT 


OVERVIEW 


The CTOS Operating System includes a number of 
system service processes. These processes, which 
are scheduled for execution in the same manner as 
application processes, receive IPC messages to 
request the performance of their services. Any 
process, even a system service process, can use 
(be a client of) a system service process. 

Each system service process acts as the system- 
wide guardian and manager for a class of system 
resources, such as files, memory, or the 
Convergent keyboard. Because the system service 
process is the only software element that 
accesses the resource, and because the interface 
to the system service process is formalized 
through the use of IPC, a highly modular 
environment results. 

This modular environment increases reliability by 
localizing the scope of processing and provides 
the flexibility to replace a system service 
process as a complete entity. 

System builders can also include their own system 
service processes, which are then indistinguish- 
able from Convergent processes. 

In the "Interprocess Communication Management" 
section, see the following subsections for more 
details: "System Service Processes," "Accessing 
System Services," "Procedural Access to System 
Services," "Direct Access to System Services," 
"Interaction of Client Processes and System 
Service Processes," "Filter Processes," "Request 
Blocks," "Request Primitive," "Respond 
Primitive," "Wait Primitive," and "Interstation 
Communication. " 
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CONCEPTS 


A system service process can toe added to the 
Operating System in three ways. It can be: 


o 

linked into 

the CTOS System Image 

t 

o 

dynamically installed in 
partition, or 

an extended system 

o 

dynamically 

application 

installed 
partition . 

in a 

secondary 

The 

request codes served 

by a 

dynamically 


installed system service process must be reserved 
at system build. (See the System Programmer 1 s 
Guide for details on linking into the CTOS System 
Image and on system build.) 


Dynamically Installing a System Service 
in an Extended System Partition 

A system service process that is to be 
dynamically installed in an extended system 
partition is first linked into its own self- 
contained task image. The system service process 
must be self-installing. It is installed with 
the Executive's Run File command or its own 
command (created with the Executive's New Command 
command). (See the Executive Manual for more 
information about these two commands.) 

Once installed, the system service is permanent 
and cannot be removed except by system reload. 
The location of the extended system partition 
depends on whether any secondary application 
partitions have been created before the system 
service is installed. 

o If the system service process is installed 

before any secondary application partition is 
created, the extended system partition is 

placed at the highest available memory 
location . 

o If the system service process is installed 

after a secondary application partition is 
created, the extended system partition is 

located between the secondary and primary 
application partitions. 
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Typical Operational Sequence 


A typical sequence of operations for a self- 
installing system service process might include: 

1. The ChangePriority operation (see the 
"Process Management" section) to change its 
priority appropriately. 

2. The AllocMemorySL or DeallocMemorySL 

operation to allocate/deallocate the short- 
lived memory segment of an application 
partition (if different from the size of its 
run file) . It may be efficient to place 

initialization code (which is never reused) 
in the lowest address locations of the task 
image and to use DeallocMemorySL to 
deallocate the memory that contains this 
initialization code before step 6 below. 

3. The AllocExch operation (see the "Exchange 
Management" section) to allocate a service 
exchange and any other exchanges needed for 
its internal operation. 

4. The CreateProcess operation (see the "Process 
Management" section) to create any additional 
processes needed for its operation. 

5. The ServeRq operation (described later in 

this Section) for each request code it is to 
serve. Specify the service exchange 

allocated in step 3 above. The number of 
request codes is specified at system build. 

Request codes 0 through 7FFFh are reserved by 
Convergent Technologies for future expansion 
and should not be used by system builders. 
Request codes 8000h-0FFFFh are available for 
system builder use. (Appendix D lists the 
request codes . ) 

6. The ConvertToSys operation (described later 
in this Section) to convert its processes, 
short-lived memory, and exchanges to system 
service processes, system memory, and system 
exchanges, respectively. This prevents these 
resources from being released during Chain, 
ErrorExit, and Exit operations (see the "Task 
Management" section) . 

7. The Chain operation to load the specified 
exit run file as the succeeding application 
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system. Chain normally returns to the 
application system only if it fails. 
However, in the special case described in 
this sequence. Chain always returns. 
Therefore the call to Chain should not be in 
the initialization code that is overlaid by 
the new application system. 


Restrictions 


The following restrictions are to avoid conflict 
with the Chain, ErrorExit, and Exit operations 
initiated by the application system. After using 
ConvertToSys in step 6 above, a system service 
process must: 

o use the OpenFileLL, rather than the OpenFile, 
operation (described in the "File Management" 
section) , 

o not use the CloseAl lFiles or CloseAl lFilesLL 
operations (described in the "File 
Management" section) , 

o not allocate or deallocate exchanges, 

o not allocate or deallocate memory, 

o not create processes, and 

o not use the Chain (other than as described in 
step 7 above), ErrorExit, or Exit operations. 


Dynamically Installing a System Service in a Secondary 
Application Partition 

A system service is installed in a secondary 
application partition by the process executing in 
the primary application partition with the 
LoadPrimaryTask operation. (See the "Application 
Partition Management" section. ) A system service 
installed in a secondary partition is not 
permanently installed and can be removed by 
application partition management operations. 

A system service executing in a secondary 
application partition must not use the 
ConvertToSys operation, because doing so would 
prevent its dynamic removal. Also, it should use 
the Chain operation only to remove itself, not to 
replace the current application system with a 
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specified run file. Since a system service in a 
secondary application partition has a unique user 
number, it is not subject to the restrictions 
noted above for a system service installed in an 
extended system partition. 
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OPERATIONS : SERVICES 


System services management provides the 
operations listed below. 

ConvertToSys converts all processes, short- 

lived memory, and exchanges in 
the primary application 
partition to system service 
processes, system memory, and 
system exchanges, respectively. 

ServeRq is used by a dynamically 

installed system service 
process to declare its 
readiness to serve the 
specified request code. 
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Conve r tToSys 
Description 


The ConvertToSys service converts all processes, 
short-lived memory, and exchanges in the primary 
application partition to system service 
processes, system memory, and system exchanges, 
respectively . 

Procedural Interface 

ConvertToSys: ErcType 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

98 
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Serve Rq 


Description 

The ServRq service is used by a system service 
process that is dynamically installed to serve 
the specified request code. Future requests 
containing the specified request code are queued 
at the specified exchange. 

Specifying exchange 0 indicates that the calling 
process is no longer serving the specified 
request code. However, this does not dequeue 
currently queued requests at the exchange that 
was formerly associated with the specified 
request code. Status code 33 ("Service not 

available") is returned to future requests 
containing the specified request code. 

Procedural Interface 

ServeRq ( requestCode , exchange): ErcType 

where 

requestCode is the request code. 

exchange is the service exchange number or 0. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

99 

12 

requestCode 

2 


14 

exchange 

2 
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14 FILE MANAGEMENT 


OVERVIEW 


The file management system provides a 
hierarchical organization of disk file data by 
node, volume, directory, and file. Volumes are 
automatically recognized when placed online. 
Each file can have a 50-character file name, a 
12-character password, and a file protection 
level. A file can be dynamically expanded and 
contracted without limit as long as it fits on 
one disk. Concurrent access is controlled by 
read (shared) and modify (exclusive) access 
modes . 

While providing convenience and reliability, the 
file management system supplies the system 
builder with the full throughput capability of 
the disk hardware. This includes reading or 
writing any 512-byte sector of an open file with 
one disk access, reading or writing up to 65k 
bytes with one disk operation, input/output 
overlapped with process execution, and optimized 
disk arm scheduling. 

In a cluster configuration, files can be located 
at cluster workstations as well as at the master 
workstation . 

The file management services of the CTOS OS are 
efficient, reliable, and convenient to use. 

Efficiency is provided through: 

o careful data placement. 

The volume control structures resident on 
each volume are placed to minimize disk arm 
movement . 

The Volume Home Block is brought into memory 
when a volume is placed online. In addition, 
the most recently used directory information 
is retained in memory. 

o randomization (hashing) techniques. 

These techniques reduce the number of disk 
reads required to access directory 
information. These techniques are used for 
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placing an entry in a directory and are later 
used for locating it. 

Reliability is provided through: 

o multilevel (volume, directory, or file) 
password protection. 

o multiple file protection levels. 

A file protection level specifies the access 
allowed to a file when the accessing process 
does not present a valid volume or directory 
pas sword . 

o duplication of two volume control 
structures: the Volume Home Block and the 

File Header Blocks. 

This duplication ensures that damage to one 
copy of a volume control structure does not 
cause a loss of data. 

Convenience is provided through: 

o hierarchical organization of disk file data 
by node, volume, directory, and file. 

o long file names (up to 50 characters). 


o dynamic file length. 

The user determines the file length when the 
file is created and can change it later. 


o 

removable file volumes 

( floppy disks ) . 

o 

automatic recognition 

online . 

of 

volumes placed 

o 

read (shared) or modify 
modes . 

(exclusive) file 

o 

device independence. 




The device on which a file is located is 
transparent to the user. 


File Access Methods 

File access methods augment the file management 
system by providing more structured access to 
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disk file data, 
methods : 


There are four file access 


o 

o 

o 

o 


the Sequential Access Method, 

the Record Sequential Access Method, 

the Direct Access Method, and 

the Indexed Sequential Access Method (ISAM). 


The first three access methods are described in 
detail in sections of those names in this 
Manual. The fourth access method is described in 
the ISAM Manual. 


Local File System 

A cluster workstation can have its own local file 
system. The local file system allows a cluster 
workstation to access files on local mass storage 
as well as files on mass storage at the master 
workstation. The file system filter process of 
the cluster workstation intercepts each file 
access request and directs it either to the local 
file system or to the master workstation. 

A cluster workstation can be bootstrapped either 
from a file at the master workstation or from its 
local file system. A cluster workstation 
bootstrapped from its local file system is a 
self-contained entity that accesses the master 
workstation only for shared files. If a 
malfunction occurs at the master workstation, the 
cluster workstation can continue to operate 
normally, provided all file accesses are to local 
mass storage. 
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CONCEPTS 


The file management system has a hierarchical 
organization of disk file data toy node, volume, 
directory, and file. 


Node 


A Convergent system connected to a CT-NET Network 
can access the files of other network nodes, 
subject to password protection. The node at 
which a file is located must be specified for 
files not located at the same node as the 
requesting process. 


Volume 


The files of the system are located on volumes. 
A volume is the media of a disk drive that was 
formatted and initialized using the IVolume 
utility. (See the System Utilities Manual .) It 
is protected by a volume password. 

For example, a floppy disk and the media sealed 
inside a Winchester disk drive are volumes. A 
floppy disk is a removable volume. 

A volume contains a number of volume control 
structures.: . the Volume Home Block, the File 
Header Blocks, and the Master File Directory, 
among others. (These structures are described in 
detail in "Volume Control Structures" below.) 

11,116 V°i ume Home Block is the root structure of 
information of a disk volume. The File Header 
Block of each file contains information about 
that file and about the disk address and size of 
each of its Disk Extents . (A Disk Extent is one 
or more contiguous disk sectors.) The Master 
File Directory (which contains an entry for each 
directory on the volume) and the directories 
provide fast access to the File Header Block of a 
specific file. They do not, however, contain any 
information about the file that is not also 
contained in its File Header Block. 

There are duplicate Volume Home Blocks (working 
and initial copies) and duplicate File Header 
Blocks (primary and secondary copies) on the 
volume for reliability. The primary and 

secondary copies of the File Header Blocks are 
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located on different cylinders and at different 
rotational positions and are accessed (except for 
floppy disks) by different read/ write heads. 
These duplicates ensure that damage to one copy 
does not cause a loss of data. 

The location on the volume of the Volume Home 
Blocks, the File Header Blocks, and the other 
volume control structures minimizes disk arm 
movement and therefore maximizes efficiency. The 
File Header Blocks are located in a single area 
of the volume, the disk address and size of which 
are recorded in the working and initial copies of 
the Volume Home Block. Volume control structures 
that are frequently accessed, including the 
primary and secondary copies of the File Header 
Blocks, are located near the middle of the disk. 


Directory 


The files of a volume are divided into one or 
more directories. A directory is a collection of 
related files on one volume . The maximum number 
of directories that can be created on a volume 
depends on the size of the Master File Directory; 
its size is specified when the volume is 
initialized. The maximum number of files that 
can be created in a directory depends on the 
directory's size, which is specified when the 
directory is created. A directory is protected 
by a directory password. 

A directory is created with the CreateDir 
operation and deleted with the DeleteDir 

operation. 


File 


A file is a set of related records (on disk) 
treated as a unit. The files of a volume consist 
of integral numbers of 512-byte sectors and must 
be completely contained on the disk. There are 
no other restrictions on file size. A file is 
protected by a file protection level and by an 
optional file password. 

A file is created with the CreateFile operation 
and deleted with the DeleteFile operation. Once 
it is created, it is accessed with the OpenFile 
operation and closed with the CloseFile 
operation. The ChangeFileLength operation 
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changes the length of an open file. The 
RenameFile operation renames an existing file. 


Automatic Volume Recognition 

The OS automatically recognizes volumes placed 
online (that is, mounted). For example, when a 
floppy disk is inserted into a disk drive, the OS 
reads the disk to determine whether it contains a 
volume and, if it does, that no other volume of 
the same name is already online. After this 
validation by the OS, the volume responds to user 
requests containing appropriate specifications 
and passwords. 

When a volume is placed online, the Volume Home 
Block is read into memory. It remains there as 
long as the volume remains online. 

If a floppy drive door is opened, any open files 
on the disk in that drive are automatically put 
into a special dismounted state. Such files can 
be closed as usual, but any attempt to perform 
other operations on them returns status code 216 
("Wrong volume mounted"). 


Node Name 

A node name is a string of characters. It can 
have a maximum of 12 characters. * 


Volume Name 

A volname (volume name) is a string of 
characters. It can have a maximum of 12 
characters . 

System Volume 

The volume on which the OS resides can be 
referenced in two ways: by its synonym, Sys, or 
by the name it was given when it was initialized 
with the IVolume utility. 

In a master or standalone workstation, Sys is a 
synonym for the volume name of the device from 
which the CTOS OS is bootstrapped. 

For example, in a dual- floppy standalone system, 
where the OS is bootstrapped from the floppy disk 
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in drive 0, Sys can be used instead of the volume 
name of the floppy disk in drive 0. In a 
Winchester-based (hard disk) system, where the OS 
is bootstrapped from hard-disk drive 0, Sys can 
be used instead of its volume name. 

In a cluster workstation without local disk 
storage, Sys is a synonym for the volume name of 
the device from which the master workstation of 
that cluster system is bootstrapped. 

In a cluster workstation bootstrapped from its 
local disk, Sys is a synonym for the volume name 
of the device from which the cluster workstation 
is bootstrapped. 

• Sys is a synonym for the volume name of the 
device from which the master workstation of the 
cluster is bootstrapped. 


Scratch Volume 


The volume on which scratch (temporary) files are 
placed can be referenced either by its synonym, 
Scr, or by its real name. 


Directory Name 


A dirname (directory name) is a string of 
characters. It can have a maximum of 12 
characters . 


File Name 


A filename 
characters . 
characters . 


(file name) is a string of 
It can have a maximum of 50 


* 


* 


Directory and File Specifications 

A directory is referred to with a directory 
specification. A directory specification has the 
form: ~ 

{node} [ volname]dirname 
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A file is referred to with a file specifica- 
tion. A full file specification has the form: 

{ node } [ vo lname ] < di r name > f i 1 ename 

The distinction between uppercase and lowercase 
in directory and file specifications is not 
significant in matching directory and/or file 
names during directory lookup; the distinction 
is, however, preserved by the file management 
system to make the directory and file 
specifications easier to read. For example, a 
file can be created with the specification: 

[MasterVol] <Susan>Todays>work 

The same file can later be accessed as: 

[mastervol] <SUSAN> todays >Work 

It is recommended that node names, volume names, 
and directory names consist only of alphanumeric 
characters, plus the period, and the hyphen. 

It is recommended that file names consist of 
alphanumeric characters, plus the period, " • " , 
the hyphen, and the right angle bracket, 

II s II 
* • 


Abbreviated Specifications 

A file or directory can be referred to with an 
abbreviated specification if default specifica- 
tions were previously established. 

The SetPath operation establishes a default node, 
a default volume, a default directory, and a 
default password. (See "Passwords" below.) The 
SetPrefix operation establishes a default file 
prefix. SetPath and SetPrefix establish defaults 
for the user number of the calling process. A 
unique user number is associated with each 
application partition. 

If a SetPath operation is issued with the default 
volname of [MasterVol] and the default dirname of 
<Susan>, the user can access the files: 

[Mastervol] <Susan>Todays>work 
[Mastervol] <Susan> Yesterdays > work 

as either: 
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<Susan> Todays > work 
< Susan > Yes ter day s > work 

if just the volname is omitted, or: 

Todays > work 
Yesterdays > work 

if the default volname and default dirname are 
omitted. <dirname> cannot be omitted unless 
C volname] is also omitted. 

If a SetPrefix operation is issued with the 
default file prefix of Todays >, in addition to 
the default volname and dirname established by 
the SetPath operation above, the user can access 
the files: 

[MasterVol] <Susan>Todays>work 
[MasterVol] < Susan> Yes terdays> work 

as : 

work 

and : 

<Susan>Yesterdays>work 

The file in the last example above could no 
longer be specified as: 

Yesterdays > work 

because the file accessed would have been: 
[MasterVol] < Susan > Today s> Yes terdays> work 
which was not what was meant. 


Passwords 

Password protection is available at three levels: 
o volume, 
o directory, or 
o file. 

A volume password protects a volume. A directory 
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password protects a directory on a volume. A 
file paTsword protects a file in a directory on a 
volume . 

Volume passwords are specified with the IVolume 
utility. Directory passwords are specified in 
the CreateDir operation. File passwords are 
specified in the SetFileStatus operation. 

Volume, directory and file passwords can consist 
of all alphanumeric characters, plus the period, 

" and the hyphen, A volume, directory, 
or file password can have a maximum of 12 
characters . 

A file can be accessed by knowledge of its 
volume, directory, or file password. Knowledge 
of a volume password allows access to all the 
directories and all the files of that volume. 
Knowledge of a directory password allows access 
to all the files of that directory. Knowledge of 
a file password permits access that is dependent 
on the file protection level specified for that 
file. (See "File Protection" below.) 

The OpenFile operation accepts a single 
password. This password is compared first 
against the volume password, then against the 
directory password, and last against the file 
password (if one was specified). Access is 
granted to open the file if any of these 
comparisons match. 

The CreateFile operation accepts a single 
password that authorizes the creation of a file 
in the specified directory. It is not a password 
to be assigned to the file being created. This 
password is compared first against the volume 
password and then against the directory 
password. Access is granted to create the file 
if either of these comparisons match. (The 
SetFileStatus operation assigns a password to the 
file being created. The CreateDir operation 
assigns a password to the directory being 
created . ) 

A default password can be specified in the 
SetPath operation. It is used whenever an 
explicit password is not specified to an 
operation. The default password, like an 
explicit one, is used in a comparison against the 
volume, directory, and file passwords (in that 
order) . 
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File Protection 


A file is assigned a file protection level. A 
file protection level specifies the access 
allowed to a file when the accessing process does 
not present a valid volume or directory password. 

A default file protection level is specified for 
the files of a directory when it is created with 
the CreateDir operation. When a file is created, 
it is assigned the default file protection level 
of the directory in which it is created. The 
file protection level of a file can be changed 
with the SetFileStatus operation. 

The file protection levels are described in Table 
14-1 below. Three levels (unprotected, modify 
protected, and access protected) ignore file 
passwords; five levels (modify password, access 
password, read password, nondirectory modify 
password, and nondirectory access password) use 
file passwords. 

The unprotected level is used for files that any 
process can read or modify. 

The modify protected, modify password, and 
nondirectory modify password levels are used for 
files that any process can read but for which a 
password is needed to modify. 

The access protected, access password, read 
password, and nondirectory access password levels 
are used for files that need a password to read 
or modify. 
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Table 14-1. 

File Protection Levels. (Page 1 of 2) 

Level 

Decimal 

Value 

Description 

unprotected 

15 

The file is unpro- 
tected. It can be read 
or modified without a 
password . 

modify 

protected 

5 

The file is modify pro- 
tected. It can be read 
without a password. A 
volume or directory 
password is needed to 
modify it. 

access 

protected 

0 

The file is read and 
modify protected. A 
volume or directory 
password is needed to 
read or modify it. 

modify 

password 

7 

The file is modify pro- 
tected. It can be read 
without a password. A 
password (volume, di- 
rectory, or file) is 
needed to modify it. 

access 

password 

3 

The file is read and 
modify protected. A 

password (volume, di- 
rectory, or file) is 
needed to read or modi- 
fy it. 

read password 

1 

The file is read and 
modify protected. A 

password (volume, di- 
rectory, or file) is 
needed to read it. A 

volume or directory 

password is needed to 
modify it. 
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Table 14-1. File Protection Levels. (Page 2 of 2) 


Level 

Decimal 

Value 

Description 

nondirectory 

23 

The file is modify pro- 

modify password 


tected. It can be read 
without a password. A 
volume or file password 
is needed to modify it; 
a directory password 
alone is insufficient. 

nondirectory 

19 

The file is read and 

access password 


modify protected. A 
password (volume, di- 
rectory, or file) is 
needed to read it. A 
volume or file password 
is needed to modify it; 
a directory password 
alone is insufficient. 
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CREATING AND ACCESSING A FILE 


The file management system provides random access 
to 512-byte sectors of a file. (512 bytes is the 
size of a physical disk sector.) The operations 
of the file management system allow reading and 
writing of multiple sectors, starting with a 
particular sector of a file. The file management 
system provides device independence by masking 
the device characteristics of the disk on which 
the file is located. 


Logical File Address 

A logical file address (lfa) is used to locate a 
particular sector of a file. It specifies the 
byte position within a file; that is, it is the 
number (the offset) that would be assigned to a 
byte in a file if all the bytes were numbered 
consecutively starting with 0. An lfa is a 32- 
bit unsigned integer that must be on a sector 
boundary and is therefore a multiple of 512. For 
example, the lfa of the third sector of a file is 
1024. 

The two high-order bits of the lfa are reserved 
as special indicators. Bit 31 is set to override 
normal system checks and is used to attempt 
access to defective disks. Bit 30 is set to 
suppress retry of input/output to recover from 
errors. For example, a program logging high- 
speed digitized wave forms that could accept 
badly written data but not the time required for 
retry, would specify an lfa of 40000400h to 
specify the third sector of a file with error 
retry suppressed. The returned status code 
reports errors in the normal way even when the 
special indicators are set. 


File Handle 


A file handle (fh) is a 16-bit integer that 
uniquely identifies an open file. It is returned 
by the OpenFile operation and is used to refer to 
the file in subsequent operations such as Read, 
Write, and DeleteFile. 

A file handle can be long-lived or short-lived. 
It is set long-lived by an OpenFileLL or 
SetFhLongevity operation. Only a short-lived 
(normal) file handle is closed by a CloseAllFiles 
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operation or automatically when an application 
system terminates. A long-lived, as well as a 
short-lived, file handle is closed by an explicit 
CloseFile operation or by the CloseAllFilesLL 
operation . 


Memory Address 

A memory address , as referred to in input/output 
operations, is always a 32-bit address that 
consists of a 16-bit segment base and a 16-bit 
offset. See the chapter on "8086 Machine 
Organization" in the Central Processing Unit for 
more information. " ~ ~ " ~ 


Using a File 

There are three steps in using a file: 

1. creating it, 

2. opening it, and 

3. reading and writing it. 


Creating a File 

The following steps occur when a CreateFile 

operation is requested: 

1. The OS verifies that a volume of the 

requested name is already online. (The 

Volume Home Block is brought into memory when 
a volume is placed online.) 

2. The OS verifies that a directory of the 
requested name is on that volume. (The most 
recently used directory information is 
retained in memory.) 

3. The OS verifies that a file of the requested 
name does not exist in that directory. 

4. The OS allocates a File Header Block and 
assigns the requested number of disk sectors 
by using the Allocation Bit Map. 

5. The OS inserts an entry for the file in the 
requested directory. 
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Opening a File 

The following steps occur when an OpenFile 

operation is requested: 

1. The OS verifies that a volume of the 

requested name is already online. (The 

Volume Home Block is brought into memory when 
a volume is placed online.) 

2. The OS verifies that a directory of the 

requested name is on that volume. (The most 

recently used directory information is 

retained in memory.) 

3. The OS verifies that a file of the requested 
name is in that directory. 

4. The OS allocates a File Control Block, one or 
more File Area Blocks, and a pointer in the 
User Control Block to the File Control 
Block. (These structures are discussed in 
"System Data Structures" below.) 

5. The OS copies the information from the File 
Header Block to the File Control Block and 
the one or more File Area Blocks. 

6. The OS returns a file handle to the user 
process. The file handle serves to identify 
this particular File Control Block. 


Reading and Writing a File 

There are three ways to read and write the 
sectors of a file: 

o with the Read and Write procedures, 

o with the ReadAsync and CheckReadAsync and 
WriteAsync and CheckWriteAsync procedures, 
and 

o with a user-constructed request block and the 
Request and Wait (or Check) primitives. 

The Read and Write procedures are the simplest 
way of doing input/output because much of the 
necessary housekeeping (for example, constructing 
a request block) and issuing the Request and Wait 
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primitives is done automatically. These two 
procedures do not provide for any overlap between 
input/output operations and computation. 

The ReadAsync and WriteAsync procedures are a 
more complex way of doing input /output . These 
two procedures allow a process to initiate an 
input/output transfer and then compute and/or 
initiate other input/output transfers before 
checking (with the CheckReadAsync and 
CheckWriteAsync procedures) for the successful 
completion of the transfer. 

The user-constructed request block and the 
Request and Wait primitives are the most complex 
way of doing input/output. They allow the 
program to overlap multiple input/output 
operations and computation in an arbitrarily 
complex manner. 


Local File System 

A cluster workstation can have its own local file 
system. The local file system allows a cluster 
workstation to access files on local mass storage 
as well as files on mass storage at the master 
workstation. The file system filter process of 
the cluster workstation intercepts each file 
access request and directs it either to the local 
file system or to the master workstation. 

When a request to open a file is intercepted, the 
filter process first routes it to the local file 
system. If the volume is not found, the request 
is routed to the master workstation. 

The user can explicitly route a file access 
request to the master workstation by including 
the special character ( ! ) before the volume 
specification . 

Files on mass storage at the master workstation 
can be accessed by any cluster workstation. 
However, files on local mass storage cannot be 
accessed from the master workstation or from 
other cluster workstations. A local file must be 
copied to the master workstation if it is to be 
processed by the master workstation, another 
workstation in the cluster, or another node. 
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A local file must be copied to the master 
workstation before it can be processed by any of 
the following: 

o printer spooler, 
o batch manager, 
o RJE, 
o ISAM, or 

o any system service executing at the master 
workstation or another cluster workstation. 

The file system filter process of the cluster 
workstation duplicates the following master 
workstation information: 

o default path information (specified in the 
SetPath operation) . This allows the GetUCB 
operation to be serviced in the cluster 
workstation . 

o date/time information (specified in the 
SetDateTime operation) . 

A cluster workstation bootstrapped from its local 
file system is a self-contained entity that must 
access the master workstation only for shared 
files. If a malfunction occurs at the master 
workstation, the cluster workstation can continue 
to operate normally provided all file accesses 
are to local mass storage. 
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OPERATIONS : 


PROCEDURES AND SERVICES 


File management operations are categorized by 
function in Table 14-2 below. 


Table 14-2. File Management Operations by Function. 

Allocation 

Defaults 

ChangeFileLength 

ClearPath 

CreateFile 

SetPath 

DeleteFile 

SetPrefix 

Access 

Directory 

CloseAllFiles 

CreateDir 

Close A1 IF ilesLL 

DeleteDir 

CloseFile 

ReadDirSector 

OpenFile 


OpenFileLL 

Other 

Input/ Output 

GetFh Longevity 


GetFileStatus 

CheckReadAsync 

GetUCB 

CheckWriteAsync 

QueryWSNum 

Read 

RenameFile 

ReadAsync 

SetFhLongevity 

Write 

SetFile Status 

WriteAsync 



Allocation 


Access 


ChangeFileLength expands or contracts an open 

file to a new length. 

CreateFile creates a file of the specified 

name in the specified directory 
on the specified volume. 

DeleteFile deletes an open file. 


CloseAllFiles closes all files that are 

currently open for the user, 
except those marked long-lived. 
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CloseAllFilesLL 

CloseFile 

OpenFile 

OpenFileLL 

Input/ Output 

CheckReadAsync 

CheckWriteAsync 

Read 

ReadAsync 

Write 

WriteAsync 


closes all files that are 
currently open for the user, 
including those marked long- 
lived . 

closes an open file. 

opens an already existing file, 
and returns a file handle. 

opens an already existing file, 
and returns a file handle 
marked long-lived. 


waits for input completion, 
checks the status code, and 
obtains the byte count of data 
read after a ReadAsync 
procedure . 

waits for output completion, 
checks the status code, and 
obtains the byte count of data 
written after a WriteAsync 
procedure . 

transfers an integral number of 
512-byte sectors from disk to 
memory. 

initiates the transfer of an 
integral number of 512-byte 
sectors from disk to memory. 

The CheckReadAsync procedure 
must be called to check the 
completion status of the 
transfer . 

transfers an integral number of 
512-byte sectors from memory to 
disk. 

initiates the transfer of an 
integral number of 512-byte 
sectors from memory to disk. 

The CheckWriteAsync procedure 
must be called to check the 
completion status of the 
transfer . 
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Defaults 


Directory 


Other 


ClearPath 


SetPath 


SetPref ix 


clears the defaults established 
by the SetPath and SetPrefix 
operations . 

establishes a default volume, a 
default directory, and a 
default password. 

establishes a default file 
prefix that is prefixed to the 
file name part of a file 
specification if that file 
specification does not have an 
explicit volume name or 
directory name. 


CreateDir 


DeleteDir 

ReadDirSector 


creates a directory of the 
specified name on the specified 
volume . 

deletes an empty directory. 

reads a 512-byte sector of the 
specified directory. 


GetFhLongevity copies the requested 

information on the longevity of 
the file handle to the 
specified area. 

GetFileStatus copies the requested status 

information to the specified 
area . 


GetUCB 


QueryUserNum 


RenameFile 


copies the User Control Block 
for the current user number to 
the specified area. 

returns the user number of the 
application system in the 
partition. 

changes the file name and/or 
the directory name of an 
existing file. A. file can be 
renamed to another directory on 
the same volume. 
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SetFhLongevity 

SetFileStatus 


sets how long a file handle is 
to survive. 

copies the specified status 
information from the specified 
memory area to the File Header 
Block. 
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ChangeFileLength 

Description 


The ChangeFileLength service expands or contracts 
the file length to a new length. The end-of-file 
pointer in the File Header Block is set to 
reflect the new length. 

Procedural Interface 

ChangeFileLength (fh, lfaNewFileSize): ErcType 
where 

fh is a file handle returned from an 

OpenFile operation. The file must 
be open in modify mode. 

lfaNewFileSize 

is the new file size in bytes. It 
must be a multiple of 512. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

13 

12 

fh 

2 


14 

lfaNewFileSize 4 
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CheckReadAsync 

Description 

After calling the ReadAsync procedure to initiate 
a read, the requesting process continues 

execution. When the process wants to synchronize 
with the asynchronous read (that is, wait for its 
completion), the process does a CheckReadAsync. 
The CheckReadAsync procedure waits for input 
completion, checks the status code, and obtains 
the byte count of data read. 

Status code 248 ("Wrong pRq argument") is 
returned if the pRq argument does not match the 
one of the preceding ReadAsync procedure. 

Procedural Interface 

CheckReadAsync (pRq, psDataRet) : ErcType 
where 

pRq is the same memory address as given 

in the pRq argument of the ReadAsync 
procedure . 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully read is to be returned. 

Request Block 

The ReadAsync and CheckReadAsync procedures are 
procedural interfaces to the Read operation. See 
the Read operation below. 
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CheckWriteAsync 

Description 


After calling the WriteAsync procedure to 
initiate a write, the requesting process 
continues execution. When the process wants to 
synchronize with the asynchronous write (that is, 
wait for its completion) , the process does a 
CheckWriteAsync. The CheckWriteAsync procedure 
waits for output completion, checks the status 
code, and obtains the byte count of data written. 

Status code 248 ("Wrong pRq argument") status 
code is returned if the pRq argument does not 
match the one of the preceding WriteAsync 
procedure . 

Procedural Interface 

CheckWriteAsync (pRq, psDataRet) : ErcType 
where 

pRq is the same memory address as given 

in the pRq argument of the 
WriteAsync procedure . 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully written is to be returned. 


Request Block 


The WriteAsync and CheckWriteAsync procedures are 
procedural interfaces to the Write operation. 
See the Write operation below. 
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Clear Path 


Description 


The ClearPath service clears the defaults 
established by the SetPath and SetPrefix 
operations . 

Procedural Interface 

ClearPath: ErcType 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

2 
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CloseAllFiles 


Description 


The CloseAllFiles service closes all files that 
are currently open for the user, except those 
marked long-lived. 

Procedural Interface 

CloseAllFiles: ErcType 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

19 
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CloseAllFilesLL 

Description 


The CloseAllFilesLL service closes all files that 
are currently open for the user, including those 
marked long-lived. 

Procedural Interface 

CloseAllFilesLL: ErcType 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

62 
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CloseFile 


Description 


The CloseFile service closes an open file. 
Procedural Interface 

CloseFile (fh): ErcType 
where 

fh is the file handle returned from an 

OpenFile operation. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

10 

12 

fh 

2 
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CreateDir 


Description 


The CreateDir service creates a directory of the 
specified name on the specified volume. The 
volume name can be defaulted to that specified in 
a previous SetPath operation. 

Status code 240 ("Directory already exists") 
status code is returned if a directory of the 
specified name already exists. 

Procedural Interface 

CreateDir (pbDirSpec, cbDirSpec, pbVolPas sword, 
cbVolPas sword, pbDirPas sword , 
cbDirPas sword, cSectors, 
defaultFileProtectionLevel ) : ErcType 

where 

pbDirSpec 

cbDirSpec describe a character string of the 
form { node ) [ volname ] dir name . 


pbVolPas sword 
cbVolPas sword 

describe the volume password that 
authorizes the creation of the 
directory on the specified volume. 


pbDirPas sword 
cbDirPas sword 

describe the directory password to 
be assigned to this directory. 

cSectors is the size of the directory in 512- 

byte sectors. 

The number of directory entries per 
sector depends on the length of the 
file names of the files created in 
the directory. An approximate value 
for the cSectors argument can be 
computed by dividing the expected 
maximum number of files ever to be 
created in the directory by 15. 

defaultFileProtectionLevel 

is the default file protection level 
to be assigned to files in this 
directory. (See Table 14-1 above.) 
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Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

reserved 

2 

14 

cSectors 

2 

16 

defaultFile- 

ProtectionLevel 

2 

18 

pb Dir Spec 

4 

22 

cbDirSpec 

2 

24 

pbVol Pas sword 

4 

28 

cbVol Pas sword 

2 

30 

pbDirPas sword 

4 

34 

cbDi r Pa s swo rd 

2 
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CreateFile 

Description 

The CreateFile service creates a file Of the 
specified name in the specified directory on the 
specified volume. 

CreateFile creates a file; it does not open it. 
The OpenFile operation opens a file after it is 
created . 

Status code 224 ("File already exists") status 

code is returned if a file of the specified name 
already exists. 

Procedural Interface 

CreateFile (pbFileSpec, cbFileSpec, pbPassword, 
cbPassword, lfaFileSize ) : ErcType 

where 

pbFileSpec 

cbFileSpec describe a character string of the 

form {node} [volname] <dirname> file- 
name. The distinction between 

uppercase and lowercase in file 

specifications is not significant in 
matching file names. 

pbPassword 

cbPassword describes a volume or directory 

password that authorizes the 

creation of a file in the specified 
directory. It is not a password to 
be assigned to the file being 

created. A password can be assigned 
to the file being created with the 
SetFileStatus operation. 

lfaFileSize is the file size in bytes. It must 
be a multiple of 512. 
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Request Block 
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DeleteDir 


Description 


The DeleteDir service deletes an empty 
directory. All the files must be deleted from a 
directory before it can be deleted. 

Status code 241 ("Directory not empty") status 
code is returned if the directory is not empty. 

Procedural Interface 

DeleteDir (pbDirSpec, cbDirSpec, pbPassword, 
cbPassword): ErcType 


where 

pbDirSpec 

cbDirSpec describe a character string of the 
form (node) [volname]dirname . 

pbPassword 

cbPassword describe the volume or directory 
password. Either password autho- 
rizes the deletion of the directory. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

18 

12 

reserved 

6 


18 

pbDirSpec 

4 


22 

cbDirSpec 

2 


24 

pbPassword 

4 


28 

cbPassword 

2 
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DeleteFile 


Description 


The DeleteFile service deletes an open file. 
Procedural Interface 

DeleteFile (fh): ErcType 
where 

fh is the file handle returned from an 

OpenFile operation. The file must 
be open in modify mode. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

6 

12 

fh 

2 
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GetFhLongevity 

Description 


The GetFhLongevity service copies the requested 
information on the longevity of the file handle 
to the specified area. 

Procedural Interface 

GetFhLongevity (fh, pCodeRet) : ErcType 
where 

fh is the file handle returned from an 

OpenFile operation. The file can be 
open in either read or modify mode. 

pCodeRet is the memory address of the word to 

which the longevity code is 
returned. If the code is 0, the 
file handle is short-lived; if it is 
1, the file handle is long-lived. 


Request Block 


sCodeRet is always 2. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

31 

12 

fh 

2 


14 

reserved 

4 


18 

pCodeRet 

4 


22 

sCodeRet 

2 

2 


14-36 


CTOS™ Operating System Manual 




GetFileStatus 


Description 

The GetFileStatus service copies the requested 

status information to the specified memory 
area. If the specified area is not large enough 
to hold the requested information, the 
information is truncated. 

Procedural Interface 

GetFileStatus (fh, statusCode, pStatusRet, 

sStatusMax): ErcType 

where 

fh is the file handle returned from an 

OpenFile operation. To get the 

password, the file must be open in 
modify mode. If the file is open in 
read mode, the file password field 
in the File Header Block is 
erased. The password fields in the 
Volume Home Block and Device Control 
Block are always erased. 

statusCode specifies the status code. Status 

items and their codes are: 


Size 

Code Item (bytes) 

0 File length 4 

1 File type 1 

2 File protection level 1 

3 Password* 13 

4 Date/time of creation 4 

5 Date/time last modified 4 

6 End-of-file pointer 4 

7 File Header Block 512 

8 Volume Home Block 256 

9 Device Control Block 100 

10 Application-specific 

field** in the File 
Header Block 64 


*The first byte of a password item 
is the number (0-12) of characters 
in the password. 

**For example, this field is used by 
Convergent Word Processor files. 
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pStatusRet 

sStatusMax describe the memory area to which 
the status information is returned. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

8 

12 

fh 

2 


14 

statusCode 

2 


16 

reserved 

2 


18 

pStatusRet 

4 


22 

sStatusMax 

2 
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GetUCB 


Description 


The GetUCB service copies the User Control Block 
for the current user number to the specified 
area. If the specified area is not large enough 
to hold the requested information, the 
information is truncated. 

The User Control Block is described in "System 
Data Structures" below. 

Procedural Interface 

GetUCB (pUcbRet, sUcbMax): ErcType 

where 

pUcbRet 

sUcbMax describe the memory area to which 

the User Control Block is copied. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

27 

12 

reserved 

6 


18 

pUcbRet 

4 


22 

sUcbMax 

2 
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OpenFile 

Description 

The OpenFile service opens an already existing 
file and returns a file handle. The file handle 
returned by OpenFile is used to refer to the file 
in subsequent operations such as Read, Write, and 
DeleteFile . 

Procedural Interface 

OpenFile (pFhRet, pbFileSpec, cbFileSpec, 

pbPassword, cbPassword, mode): ErcType 

where 

pFhRet is the memory address of the word to 

which the file handle is returned. 

pbFileSpec 

cbFileSpec describe a character string of the 
form {node} [ volname] <dirname> file- 
name. The distinction between 

uppercase and lowercase in file 
specifications is not significant in 
matching file names. 

pbPassword 

cbPassword describe the volume, directory, or 
file password that authorizes access 
to the specified file. 

mode is read (shared) or modify 

(exclusive). This is indicated by 
16-bit values representing the ASCII 
constants "mr" (mode read) or "mm" 
(mode modify) . In these ASCII 

constants, the first character (m) 
is the high-order byte and the 
second character (r or m, 
respectively) is the low-order 
byte. This is the reverse of the 
byte order of strings in Convergent 
programming languages. 

Access in read mode permits the 
returned file handle to be used as 
an argument only to the CloseFile, 
CheckReadAsync, Read, ReadAsync, 
GetFhLongevity , GetFileStatus , and 
SetFhLongevity operations. 
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Access in modify mode, however, 
permits the returned file handle to 
be used as an argument to all 

operations that expect a file 
handle . 

If the file is currently open in 

read mode, access in read mode is 

permitted but attempted access in 
modify mode causes the return of 
status code 220 ("File in use"). 

If the file is currently open in 

modify mode, attempted access in 
either read or modify mode causes 
the return of status code 220 ("File 
in use" ) . 


Request Block 


sFhMax is the size of a file handle and is always 

2 . 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

4 

12 

reserved 

2 


14 

mode 

2 


16 

reserved 

2 


18 

pbFileSpec 

4 


22 

cbFileSpec 

2 


24 

pbPas sword 

4 


28 

cbPas sword 

2 


30 

pFhRet 

4 


34 

sFhMax 

2 

2 
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OpenFileLL 

Description 

The OpenFileLL service opens an already existing 
file and returns a file handle. The file handle 
is marked long-lived and can therefore be closed 
by the CloseFile and CloseAllFilesLL operations, 
but not by the CloseAllFiles operation. The file 
handle returned by OpenFileLL is used to refer to 
the file in subsequent operations such as Read, 
Write, and DeleteFile. 

Procedural Interface 

OpenFileLL (pFhRet, pbFileSpec, cbFileSpec, 
pb Pas sword, cbPas sword, 
mode): ErcType 

where 

pFhRet is the memory address of the word to 

which the file handle is returned. 

pbFileSpec 

cbFileSpec describe a character string of the 

form {node} [volname] <dirname> file- 
name. The distinction between 

uppercase and lowercase in file 
specifications is not significant in 
matching file names. 

pbPas sword 

cbPassword describe the volume, directory, or 

file password that authorizes access 
to the specified file. 

mode is read (shared) or modify 

(exclusive). This is indicated by 
16-bit values representing the ASCII 
constants "mr" (mode read) or "mm" 
(mode modify) . In these ASCII 

constants, the first character (m) 
is the high-order byte and the 

second character (r or m, 

respectively) is the low-order 
byte. This is the reverse of the 
byte order of strings in Convergent 
programming languages. 

Access in read mode permits the 
returned file handle to be used as 
an argument only to the CloseFile, 
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CheckReadAsync , Read, ReadAsync , 
GetFhLongevity , GetFileStatus, and 
SetFhLongevity operations. Access 
in modify mode, however, permits the 
returned file handle to be used as 
an argument to all operations that 
expect a file handle. 

If the file is currently open in 
read mode, access in read mode is 
permitted but attempted access in 
modify mode causes the return of 
status code 220 ("File in use"). 

If the file is currently open in 
modify mode, attempted access in 
either read or modify mode causes 
the return of status code 220 ("File 
in use" ) . 


Request Block 


sFhMax is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

97 

12 

reserved 

2 


14 

mode 

2 


16 

reserved 

2 


18 

pbFileSpec 

4 


22 

cbFileSpec 

2 


24 

pbPas sword 

4 


28 

cbPas sword 

2 


30 

pFhRet 

4 


34 

sFhMax 

2 

2 
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QueryWSNum 

Description 


The QueryWSNum service returns the number of the 
cluster workstation. QueryWSNum returns 0 if 
executed on a standalone workstation. 

Procedural Interface 

QueryWSNum (pWSNumRet) : ErcType 

where 

pWSNumRet is the memory address of a word to 
which the number of the cluster 
workstation is returned. 

Request Block 

sWSNumRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

61 

12 

reserved 

6 


18 

pWSNumRet 

4 


22 

sWSNumRet 

2 

2 
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Read 


Description 

The Read service transfers an integral number of 
512-byte sectors from disk to memory. Read 
returns only when the requested transfer is 
complete. The ReadAsync and CheckReadAsync 

procedures are used to overlap computation and 
input/output transfer. 

To accommodate programming languages in which 
Read is a reserved word, ReadFile is permitted as 
a synonym for the Read service. 

Procedural Interface 

Read (fh, pBufferRet, sBufferMax, lfa, 
psDataRet): ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The file can be 
open in either read or modify mode. 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. The buffer must be 
word aligned. 

sBufferMax is the count of bytes to be read 

into memory. It must be a multiple 
of 512. 

lfa is the byte offset, from the 

beginning of the file, of the first 
byte to be read. It must be a 
multiple of 512. 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully read is to be returned. 
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Request Block 


ssDataRet is always 2. 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

fh 

2 

14 

If a 

4 

18 

pBuf ferRet 

4 

22 

sBuf ferMax 

2 

24 

psDataRet 

4 

28 

ssDataRet 

2 
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ReadAsync 

Description 

The ReadAsync procedure initiates the transfer of 
an integral number of 512-byte sectors from disk 
to memory. The CheckReadAsync procedure must be 
called to check the completion status of the 
transfer . 

The information returned by Read with its 
psDataRet argument and ErcType status is obtained 
by CheckReadAsync. 

Procedural Interface 

ReadAsync (fh, pBufferRet, sBufferMax, lfa, pRq, 
exchangeReply ) : ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The file can be 
open in either read or modify mode. 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. The buffer must be 
word aligned. 

sBufferMax is the count of bytes to be read to 
memory. It must be a multiple of 
512. 

lfa is the byte offset, from the 

beginning of the file, of the first 
byte to be read. It must be a 
multiple of 512. 

pRq is the memory address of a 64-byte 

area to be used as workspace by 
ReadAsync . 

exchangeReply 

is an exchange provided by the 
client process for the exclusive use 
of ReadAsync and CheckReadAsync. 

Request Block 

The ReadAsync and CheckReadAsync procedures are 
procedural interfaces to the Read operation. See 
the Read operation above. 
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ReadDirSector 


Description 

The ReadDirSector service reads a 512-byte sector 

of the specified directory. ReadDirSector is 

used primarily by the Convergent Executive. 

Procedural Interface 

ReadDirSector (pbDirSpec, cbDirSpec, pbPassword, 

cbPassword, iSector, 
pBufferRet): ErcType 

where 

pbDirSpec 

cbDirSpec describe a character string of the 
form {node} [ volname]dirname . 

pbPassword 

cbPassword describe the volume or directory 

password. Either password author- 
izes access to the directory sector. 

iSector is the number of the sector to be 

read within the directory. 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. The buffer must be 
word aligned. 
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Request Block 


sBufferMax is always 512. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

25 

12 

reserved 

2 


14 

iSector 

2 


16 

reserved 

2 


18 

pbDirSpec 

4 


22 

cbDirSpec 

2 


24 

pb Pas sword 

4 


28 

cbPas sword 

2 


30 

pBuf f erRet 

4 


34 

sBufferMax 

2 

512 
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RenameFile 


Description 


The RenameFile service changes the file name 
and/or the directory name of an existing file. A 
file can be renamed to another directory on the 
same volume. However, it cannot be moved to 
another node or volume by renaming it. 

Procedural Interface 

RenameFile (fh, pbNewFileSpec , cbNewFileSpec , 
pbPassword, cbPassword): ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The file must 
be open in modify mode. 


pbNewFileSpec 

cbNewFileSpec 

describe a character string of the 
form {node} [volname] <dirname> file- 
name. The distinction between 

uppercase and lowercase in file 
specifications is not significant in 
matching file names. 


pbPassword 

cbPassword describe a volume or directory 
password that authorizes the 
insertion of a file in the specified 
directory. It is not a password to 
be assigned to the file being 
renamed. The SetFileStatus 

operation can be used to assign a 
password to the file being renamed. 


14-50 


CTOS" Operating System Manual 



Request Block 


Offset Field 


Size 

(bytes ) Contents 


0 

sCnt Info 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

fh 

2 

14 

reserved 

4 

18 

pbNe wF i 1 e Spe c 

4 

22 

cbNewFileSpec 

2 

24 

pbPas sword 

4 

28 

cbPas sword 

2 
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SetFhLongevity 

Description 


The SetFhLongevity service sets how long a file 
handle is to survive. If the file handle is 
marked short-lived (the default condition when a 
file is first opened), it is closed by the 
CloseAllFiles , Exit, ErrorExit, and Chain 
operations. If it is marked long-lived, it is 
closed only by an explicit CloseFile operation or 
by a CloseAllFilesLL operation. 

Procedural Interface 

SetFhLongevity (fh, iCode): ErcType 

where 

fh is the file handle returned from an 

OpenFile operation. The file can be 
open in either read or modify mode. 

iCode is either 0 for a short-lived file 

handle or 1 for a long-lived one. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

30 

12 

fh 

2 


14 

iCode 

2 



14-52 


CTOS" Operating System Manual 




SetFileStatus 


Description 

The SetFileStatus service copies the specified 
status information from the specified memory area 
to the File Header Block for the file defined by 
the file handle. SetFileStatus cannot change the 
file length. The ChangeFileLength operation can 
be used to change the file length. 

Procedural Interface 

SetFileStatus (fh, statusCode, pStatus, 

sStatus): ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The file must 
be open in modify mode. 

statusCode specifies the status code. Status 

items and their codes are: 

Size 

Code Item (bytes) 

1 File type 1 

2 File protection level 1 

3 Password * 

4 Date/time of creation 4 

5 Date/time last modified 4 

6 End-of-file pointer 4 

7 invalid 

8 invalid 

9 invalid 

10 Application-specific 

field** in the File 
Header Block 64 

*The length of password is defined 
by sStatus, which must be less 
than or equal to 12. 

**This field is used 

by Convergent Word Processor 
files, for example. 

pStatus 

sStatus describe the memory area from which 

the status information is copied. 
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Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNura 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

fh 

2 

14 

statusCode 

2 

16 

reserved 

2 

18 

pStatus 

4 

22 

sStatus 

2 
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SetPath 


Description 

The SetPath service establishes a default volume, 
a default directory, and a default password. It 
also clears the default file prefix. A sub- 
sequent ClearPath operation clears the defaults. 

Procedural Interface 

SetPath (pbVolSpec, cbVolSpec, pbDirName, 
cbDirName, pb Pas sword, 
cbPas sword): ErcType 


where 


pbVolSpec 

cbVolSpec describe the default volume specifi- 
cation of the form {node }[volname). 

pbDirName 

cbDirName describe the default directory name. 


pbPas sword 

cbPassword describe the default password. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

3 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

1 

12 

reserved 

6 


18 

pbVolSpec 

4 


22 

cbVolSpec 

2 


24 

pbDirName 

4 


28 

cbDirName 

2 


30 

pbPas sword 

4 


34 

cbPassword 

2 
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SetPrefix 


Description 


The SetPrefix service establishes a default file 
prefix that is prefixed to the file name part of 
a file specification if that file specification 
does not have an explicit volume name or 
directory name. A new SetPrefix overrides a 
previous SetPrefix. The default prefix 

established by SetPrefix can be removed by: 

1. another SetPrefix that specifies a null 
string, 

2. the SetPath operation, or 

3. the ClearPath operation. 

Procedural Interface 

SetPrefix (pbPrefix, cbPrefix): ErcType 

where 

pbPrefix 

cbPrefix describe the character string that 

is to be used as a default file 
prefix . 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

3 

12 

reserved 

6 


18 

pbPrefix 

4 


22 

cbPrefix 

2 
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Write 


Description 

The Write operation transfers an integral number 
of 512-byte sectors from memory to disk. Write 
returns only when the requested transfer is 
complete. The WriteAsync and CheckWriteAsync 
procedures are used to overlap computation and 
input/output transfer. Write can also be 

accessed as the WriteFile operation. 

Attempting to write beyond the end of a file 
results in the return of status code 2 ("End of 
medium" ) . 

To accommodate programming languages in which 
Write is a reserved word, WriteFile is permitted 
as a synonym for the Write service. 

Procedural Interface 

Write (fh, pBuffer, sBuffer, lfa, 
psDataRet): ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The file must 
be open in modify mode. 

pBuffer is the memory address of the first 

byte of the buffer from which the 
data is to be written. The buffer 
must be word aligned. 

sBuffer is the count of bytes to be written 

from memory. It must be a multiple 
of 512. 

lfa is the byte offset, from the 

beginning of the file, of the first 
byte to be written. It must be a 
multiple of 512. 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully written is to be returned. 
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Request Block 


ssDataRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

36 

12 

fh 

2 


14 

If a 

4 


18 

pBuf fer 

4 


22 

sBuf fer 

2 


24 

psDataRet 

4 


28 

ssDataRet 

2 

2 


14-58 CTOS" Operating System Manual 



WriteAsync 

Description 

The WriteAsync procedure initiates the transfer 
of an integral number of 512-byte sectors from 
memory to disk. The CheckWriteAsync procedure 
must be called to check the completion status of 
the transfer. 

The information returned by Write with its 
psDataRet argument and ErcType status is obtained 
by CheckWriteAsync. 

Procedural Interface 


WriteAsync (fh, pBuffer, sBuffer, lfa, pRq, 
exchangeReply ) : ErcType 


where 

fh 


pBuffer 


sBuffer 


lfa 


pRq 


is a file handle returned from an 
OpenFile operation. The file must 
be open in modify mode. 

is the memory address of the first 
byte of the buffer from which the 
data is to be written. The buffer 
must be word aligned. 

is the count of bytes to be written 
from memory. It must be a multiple 
of 512. 

is the byte offset, from the 
beginning of the file, of the first 
byte to be written. It must be a 
multiple of 512. 

is the memory address of a 64-byte 
area to be used as workspace by 
WriteAsync . 


exchangeReply 

is an exchange provided by the 
client process for the exclusive use 
of WriteAsync and CheckWriteAsync. 


Request Block 


The WriteAsync and CheckWriteAsync procedures are 
procedural interfaces to the Write operation. 
See the Write operation above. 
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VOLUME CONTROL STRUCTURES 


A disk volume contains volume control structures 
after it is initialized with the IVolume 
utility. (See the System Utilities Manual . ) 
These structures allow the file management system 
to manage (allocate, deallocate, locate, avoid 
duplication of) the space on the volume not 
already allocated to the volume control 
structures themselves. 

The volume control structures include: 


o 

the 

Volume Home 

Block, 

o 

the 

File Header 

Blocks , 

o 

the 

Master File 

Directory , 

o 

the 

directories 

, and 

o 

the 

Allocation 

Bit Map, among 


There are duplicate Volume Home Blocks (working 
and initial copies) and (normally) duplicate File 
Header Blocks (primary and secondary copies) on 
the volume for reliability. The primary and 
secondary copies of the File Header Blocks are 
located on different cylinders and at different 
rotational positions and are accessed (except for 
floppy disks) by different read/write heads. 
These duplicates ensure that damage to one copy 
does not cause a loss of data. The IVolume 
utility permits suppression of duplicate File 
Header Blocks. However, this reduces reliability 
and is not recommended. 


The initial copy, unlike the working copy, of the 
Volume Home Block, is not modified after it is 
created. However, the primary and secondary 
copies of the File Header Blocks are always true 
duplicates . 

The location on the volume of the volume control 
structures minimizes disk arm movement. In 
particular, the structures that are necessary to 
create and open files (the working copy of the 
Volume Home Block, the File Header Blocks, the 
Master File Directory, the directories, and the 
Allocation Bit Map) are located near one another 
and near the middle of the disk. The initial 
copy of the Volume Home Block is located near the 
start of the disk. Both the primary and 
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secondary copies of the File Header Blocks are 
located in a single area, the disk address and 
size of which are recorded in the working and 
initial copies of the Volume Home Block. 

Figure 14-1, below, shows the interrelationships 
of the volume control structures. 


Volume Home Block 

There is a Volume Home Block (VHB) for each 
volume. The VHB is the root structure (that is, 
the starting point for the tree structure) of 
information of a disk volume. The VHB contains 
information about the volume such as its name and 
the date it was created. The VHB also contains 
pointers to the Allocation Bit Map, the Bad 
Sector File, the File Header Blocks, the Master 
File Directory, the directories, the System 
Image, the Crash Dump Area, and the Log File. 
The VHB is 1 sector in size. (See Table 14-3 on 
the Volume Home Block below.) 


Allocation Bit Map and Bad Sector File 

The Allocation Bit Map controls the assignment of 
disk sectors. It has 1 bit for every sector on 
the disk and the bit is set if the sector is 
available. The size of the Allocation Bit Map 
depends on the size of the volume. If a sector 
of a disk is unusable, there is an entry in the 
Bad Sector File . The Bad Sector File is 1 sector 
in size . 


File Header Block 

There is a File Header Block (FHB) for each 
file. The FHB of each file contains information 
about that file such as its name, password, 
protection level, the date/time it was created, 
the date/time it was last modified, and the disk 
address and size of each of its Disk 
Extents. The FHB is 1 sector in size. (See 
Table 14-4 on the File Header Block below.) 


Disk Extent 

A Disk Extent is one or more contiguous disk 
sectors that compose all or part of a file. The 
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Figure 14-1. Volume Control Structures. 
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entry for the Disk Extent in the FHB is 8 
bytes: 4 bytes specify its location and 4 bytes 
specify its size. 



Table 14-3. Volume Home Block. 


Offset Field 

Size 
(bytes ) 

0 

checksum 

2 

2 

lfaSysImageBase 

4 

6 

cPagesSys Image 

2 

8 

lfaBadBlkBase 

4 

12 

cPagesBadBlk 

2 

14 

lfaCrashDumpBase 

4 

18 

cPagesCrashDump 

2 

20 

volName* 

13 

33 

volPassword* 

13 

46 

lfaVhb 

4 

50 

lfalnitialVhb 

4 

54 

creationDT 

4 

58 

modif icationDT 

4 

62 

lfaMfdBase 

4 

66 

cPagesMfd 

2 

68 

lfaLogBase 

4 

72 

cPageLog 

2 

74 

currentLogPage 

2 

76 

currentLogByte 

2 

78 

lfaFileHeadersBase 

4 

82 

cPagesFileHeader 

2 

84 

altFileHeaderPageOf f set 

2 

86 

iFreeFileHeader 

2 

88 

cFreeFileHeaders 

2 

90 

cluster Factor 

2 

92 

defaultExtend 

2 

94 

allocSkipCnt 

2 

96 

lfaAllocBase 

4 

100 

allocPageCnt 

2 

102 

lastAllocPg 

2 

104 

lastAllocWd 

2 

106 

lastAllocBit 

2 

108 

cFreePages 

4 

112 

idev 

2 

114 

rgLruDirEntries ( sRgLruDirEntries ) 105 

219 

magicWd 

2 

*The 

first byte contains the character 

count . 
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Table 14-4. File Header Block. 


Offset Field 


Size 
(bytes ) 


0 

checksum 

2 

2 

fileHeaderPageNum 

2 

4 

f ileName* 

51 

55 

password* 

13 

68 

dirName* 

13 

81 

fileHeaderNum 

2 

83 

extensionHeaderNumChain 

2 

85 

header SequenceNum 

1 

86 

f ileClass 

1 

87 

accessProtection 

1 

88 

lfaDirPage 

4 

92 

creationDT 

4 

96 

modi f icat ionDT 

4 

100 

accessDT 

4 

104 

expirationDT 

4 

108 

fNoSave 

1 

109 

fNoDirPrint 

1 

110 

fNoDelete 

1 

111 

If aEndOf File 

4 

115 

default Expans ion 

4 

119 

freeRunlndex 

2 

121 

vda( runsPerFhb) 

128 

249 

runLength ( runsPerFhb) 

128 

377 

(reserved for CT expansion) 

71 

448 

application-specific field 

64 


*The first byte contains the character count. 


Extension File Header Block 

A FHB can accommodate 3 2 Disk Extents. A file 
that contains more than 32 Disk Extents requires 
extension File Header Blo cks . Extension FHBs 
are seldom necessary unless the user places an 
unusually heavy burden on the file management 
system by, for example, expanding the same file 
many times or fragmenting the available disk 
space by frequently deleting and creating files 
on a nearly full volume that is seldom 
refreshed. (A volume is refreshed by using the 
Backup Volume, iVolume, and Restore utilities. 
See the System Utilities Manual for more details 
about these utilities . ) 
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Master File Directory and Directories 


There is an entry for each directory on the 
volume in the Master File Directory (MFD) , 
including the Sys Directory (see below). The 
position of an entry within the MFD is determined 
by randomization (hashing) techniques. The entry 
contains the directory's name, password, 
location, and size. (See Table 14-5 on the Entry 
for a Directory in the MFD below.) 


Table 14-5. Entry tor a Directory in the Master File Directory. 


Offset 

Field 

Size 
(bytes ) 

0 


dirEntryName* 

13 

13 


password* 

13 

26 


lfaBase 

4 

30 


cPages 

2 

32 


defaultAccessCode 

1 

33 


IruCnt 

2 

*The 

first byte contains the 

character count. 


There is an entry for each file in one of the 
directories on the volume. The position of an 
entry within a directory is determined by 
randomization (hashing) techniques. The entry 
contains the file's name and a pointer to the 
File Header Block. 

The MFD and the directories provide fast access 
to the File Header Block of a specific file. 
They do not, however, contain any information 
about the file that is not also contained in its 
File Header Block. (The most recently used 
directory information is retained in memory.) 


System Directory 


The Sys (tern) Directory is different from other 
directories in two ways. First, when a volume is 
initialized, its MFD contains only one entry and 
that is for the Sys Directory. (The other 
directories are created by the CreateDir 
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operation.) Second, the Sys Directory contains 
entries for all system files. These files must 
not be deleted, renamed, or overwritten. 

These file entries are required in the Sys 
Directory of each volume: 

o the Bad Sector File ( BadBlk. Sys ) , 

o the Master File Directory (Mfd.Sys), and 

o the File Header Blocks ( FileHeaders . Sys ) . 
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SYSTEM VOLUME 


The Sys (tern) Directory of the Sys ( tem) Volume 
contains entries for system files that are not 
necessary in the Sys Directories of other 
volumes. These additional entries must be placed 
in [Sys]<Sys> when the volume is initialized. 
Sys Image . Sys , CrashDump . Sys , and Log. Sys are 

created (but not initialized) by the IVolume 
utility. The other file entries are created 

using the CreateDir operation or the Create 
Directory command ( see the Executive Manual ) . 


These system files are: 


o 

the System 
nnn> Sys Image 

Images 
• Sys ) , 

( Sys Image . Sys and 

WS- 

o 

the Crash Dump Areas (CrashDump. Sys 

WSnnn>CrashDump.Sys) , 

and 

o 

the Log File 

( Log . Sys ) 

/ 


o 

the standard 

character 

font (Sys. Font). 


For 

information 

on other 

initialization files, 


including the Executive and Debugger, see the 
Release Notice for the current CTOS version and 
the section on "Getting Started" in the System 
Programmer ' s Guide . 


System Image 


The System Image (the file Sys Image .Sys ) contains 
a run-file copy of the OS for the standalone or 
master workstation. 

In a cluster system, the CTOS OS for the cluster 
workstations also must be placed in this volume 
and directory in the file WSnnn > Sys Image . Sys 
where nnn is the workstation type~ as follows: 

000 standard IWS workstation 
255 AWS-210 

254 AWS-220 and -230 

253 AWS-240 

If the file W Snnn >Sys Image . Sys does not exist, 
WS > Sys Image . Sys is reset. 

See the System Programmer ' s Guide for more 
detail . 
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Crash Dump Area 


The Crash Dump Area (the file CrashDump . Sys ) 
contains a binary memory dump for the standalone 
or master workstation in the event of a system 
failure . 

The files W Snnn> CrashDump . Sys (if they exist) 
contain binary memory dumps for cluster 
workstations in the event of system failures at 
the cluster workstations. In the file 
specification, nnn is the workstation 
identification of the cluster workstation. 
(Crash Dump files are created with the CreateFile 
operation . ) 

If the files W Snnn >CrashDump ♦ Sys do not exist, 
the memory dump is made to the file 
WS>CrashDump . Sys (if it exists). This file 
eliminates the need for a Crash Dump file for 
each cluster workstation. 


Log File 


The Log File (the file Log. Sys) is an error- 
logging - file . An entry is placed in the Log File 
for each recoverable and nonrecoverable device 
error. This file can be used as a general- 

purpose logging file, for example, to write 
entries for accounting information for system 
services. The PLog utility (see the System 
Utilities Manual ) prints the content of this 
file . 


Standard Character Font 

The standard character font is loaded from the 
file Sys. Font into the font RAM (except on an AWS 
workstation, which has the standard character 
font in ROM) . 


$ Directories 


The $ Directories are special directories 
required for the Convergent software to operate 
correctly. When a request with the directory 
name of <$> is given as part of a file 
specification to the OS, the directory name is 
expanded to the form <$ nnn> , where nnn is the 
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user number of the application partition. This 
expansion occurs only if the directory name is 
<$> . 

For example, the following file specifications 
are expanded as shown when they are part of a 
request from an application system in the primary 
application partition of a standalone or master 
workstation (user number 0): 


[Vol] <$> Filename 

to 

[Vol] <$000>Filename 

<$>Filename 

to 

< $000> Filename 

[Vol] <$xyz> Filename 

to 

[Vol] <$xyz>Filename 

If an application system in 
(with user number 3, for 
request with a directory 
expanded as follows: 

a cluster workstation 
example,) generates a 
name of <$>, it is 

[Vol] <$>Filename 

to 

[Vol] <$0 03 > Filename 


All Convergent software that uses temporary files 
attempts to place those files in the [Sys]<$> 
directory first, and, if that fails, then in the 
logged- in volume and directory. 

Since the user number (s) of a cluster workstation 
are reassigned whenever the system is 
bootstrapped, the $ directories should not be 
used for permanent files. 
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SYSTEM DATA STRUCTURES 


System data structures are data areas contained 
within the OS and necessary for its operation. 
They are often configuration-dependent. The five 
system data structures related to the file 
management system are: 


o 

the 

User 

Control Block, 


o 

the 

File 

Control Block, 


o 

the 

File 

Area Block, 


o 

the 

Device Control Block, 

and 

o 

the 

I/O 

Block. 


The 

User Control Block and 

the 

Block 
below . 

are 

user-accessible 

and 


Device Control 
are described 


User Control Block 

There is a User Control Block (UCB) for each user 
number. The UCB contains the default volume, 
default directory, default password, and default 
file prefix set by the last SetPath and SetPrefix 
operations. (See Table 14-6 on the User Control 
Block below.) 

There is a user number for each application 
partition . 


Table 14-6. User Control Block. 



Size 

Offset 

Field 

(bytes ) 

0 

loglnld 

2 

2 

de faultVol* 

13 

15 

defaultDir* 

13 

28 

defaultPas sword* 

13 

41 

prefix* 

41 

82 

verifyCode 

1 

*The 

first byte contains the character 

count . 
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UCBs reside in master and cluster workstations as 
discussed below. 


User Control Blocks in the Master Workstation 


Two types of 

workstation: 

UCBs 

reside in 

the 

master 

o 

local UCBs for 

partitions, and 

secondary 

application 

o 

remote UCBs 
workstations . 

for 

file access 

by 

cluster 


Local UCBs are allocated for secondary- 
application partitions created within the master 
workstation. They are associated with Batch 
Control Blocks and Partition Descriptors, and are 
statically allocated by the OS. 

Remote UCBs are allocated for tasks located in 
cluster workstations that access files at the 
master workstation. They are dynamically 
allocated and deallocated by the OS. 


User Control Blocks in Cluster Workstations 

Local UCBs are allocated in the cluster 
workstation for the local file system. They are 
associated with Batch Control Blocks and 
Partition Descriptors, and are statically 
allocated by the OS. 


Device Control Block 

There is a Device Control Block (DCB) for each 
physical device. The DCB contains information, 
generated at system build, about the device. For 
a disk, the information includes how many tracks 
are on a disk, the number of sectors per track, 
etc. The DCB points to a chain of I/O Blocks. 
(See Table 14-7 on the Device Control Block 
below . ) 
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Table 14-7. Device Control Block. 




Size 

Offset 

Field 

(bytes ) 


0 

fMountable 

1 

1 

fNonSharable 

1 

2 

f DoubleDensity 

1 

3 

fNoMultiTrack 

1 

4 

f Attention 

1 

5 

fTimeout 

1 

6 

devName* 

13 

19 

devPas sword* 

13 

32 

control lerNum 

1 

33 

iUnit 

1 

34 

state 

1 

35 

unitStatus 

1 

36 

deviceClass 

1 

37 

cUsers 

1 

38 

oVhb 

2 

40 

olobFirst 

2 

42 

olobAct ive 

2 

44 

lfaMax 

4 

48 

If aMask 

2 

50 

verifyKey 

2 

52 

ovlyProcOpen 

2 

54 

ovlyProcClose 

2 

56 

cRetryMax 

2 

58 

cSof tErrors 

2 

60 

cHardErrors 

2 

62 

cur rentCy Under 

2 

64 

sector SizeCode 

1 

65 

gapLength 

2 

67 

data Length 

1 

68 

bytesPerSector 

2 

70 

sectors Per Track 

2 

72 

tracks Per Cylinder 

2 

74 

cylinders Per Disk 

2 


*The first byte contains the character count. 
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15 QUEUE MANAGEMENT 


OVERVIEW 


The queue management facility controls named, 
priority-ordered, disk-based queues. The files 
that contain these queues are called queue entry 
files . Each queue entry file contains 
information for a single type of processing, such 
as spooled printing, batch processing, or remote 
job entry (RJE). This information is created, 
accessed, and modified by both client processes 
and server processes such as the printer spooler, 
batch manager, or RJE. Because the queue entry 
files are disk-based, their contents are immune 
to system failures. 

In a cluster configuration, the queue management 
facility must be installed at the master 
workstation. However, the server processes that 
use the queue management facility can be 
installed at cluster workstations as well as at 
the master workstation. Multiple server 
processes in different cluster workstations can 
serve the same queue simultaneously. 

The system adminstrator defines the queues to be 
used in the system. Each queue is assigned a 
unique name and a queue entry file specification. 

Client processes can then add queue entries by 
using operations in which a queue entry file is 
referenced by a queue name. The client process 
need not specify the location of the server 
process. The first available server process in 
the cluster can serve the queue entry. 

Figure 15-1 shows an example of a cluster 
configuration with the queue management facility, 
a client process, and a server process (printer 
spooler) . 


Queue Management 


15-1 




Figure 15-1. Example Configuration with Queue Management Facility. 
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CONCEPTS 

The queue management facility acts as a central 
switch between client and server processes. 


Client Processes 

Client processes submit requests for processing 
services, such as printing, transmission, and 
batch processing of files, to the queue 
manager. By using the queue management facility, 
client processes can: 

o access queue entry files by using operations 
that specify the queue name, 

o submit entries to the appropriate queue entry 
file , 

o delete previously queued entries, and 
o obtain a list of entries queued. 


Server Processes 

Server processes (such as the printer spooler, 
RJE , and batch manager) serve the queue entry 
files. The queue management facility allows 
server processes to: 

o specify the queue (s) (and therefore the queue 
entry files) they will serve, 

o process entries in the specified queue(s), 
and 

o request the removal of queue entries that are 
processed . 


Sequence for Using the Queue Management Facility 

A simplified sequence for installing and using 
the queue management facility is described below. 

1. The system administrator creates a queue 
index file in the master workstation. The 
queue index file is a system-wide text file 
that defines the queues to be used in the 
system. The queue index file assigns to each 
queue a queue entry file for storing queue 
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entries submitted by client processes, the 
size of the queue entry, and the queue type. 

2. The queue manager is installed in the master 
workstation with the Install Queue Manager 
utility. Typically, this is part of a submit 
or batch job control file when the system is 
bootstrapped . 

3. After the queue manager is installed, it 
opens the queue entry files named in the 
queue index file. The queue entry files are 
maintained in the master workstation. 

4. A server process (such as a printer spooler, 
RJE, or batch manager) wishing to serve a 
particular queue uses the Establish- 
QueueServer operation to establish itself as 
an active server. 

5. A client process adds entries to the 

specified queue entry file with the 
AddQueueEntry operation. 

6. The server process obtains for processing a 

particular queue entry with the 

MarkKeyedQueueEntry , or the next available 
queue entry with the MarkNextQueueEntry 
operation. The queue manager marks the queue 
entry as being in use to prevent other server 
processes from operating on it. The marked 
queue entry remains in the queue entry file 
until it is removed (see next step). 

7. The server process services the marked queue 
entry, then removes the processed entry from 
the queue entry file with the 
RemoveMarkedQueueEntry operation . 

8. When the server process no longer wishes to 
serve a queue, it removes itself from the 
list of active servers with the Terminate- 
QueueServer operation. 


Queue Index File 


The queue index file is a system-wide text file 
that defines the queues to be used in the 
system. It contains information such as the name 
of each queue to be used in the system and the 
associated queue entry file. 
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The system administrator must create the queue 
index file [Sys] <Sys>Queue . Index in the master 
workstation . 

The queue index file is created with the Text 
Editor or Word Processor. A record of the 
following format is required for each queue: 

queueName/f ileSpec/entrySize/queueType < RETURN > 


where 


queueName 


f ileSpec 


entrySize 


queueType 


is a user-defined queue name that is 
unique to the installation. The 
name can be any name of up to 50 
characters, except the following 
system device names: Comm, Kbd, 

Lpt , Nul, Ptr, Tape, Vid, and X25. 
Examples of acceptable names are: 
SpoolerA, SPL, PrinterX, BatchCarol, 
Centronix, Diablo, and RJEtoBoston. 

is the file specification of the 
queue entry file in which queue 
entries submitted by client 
processes are stored (for example, 
[Winl] < Sys > Spooler AQueueEntryFile) . 

is the size of an entry for the 
queue entry file. The size is the 
number of 512-byte sectors per 
entry. For example, to define 1024- 
byte entries, specify an entry size 
of 2. In this case, 984 bytes are 
usable and 40 are reserved for the 
queue manager. 

is the type of the queue (an integer 
less than or equal to 255), which 
enables a consistency check. The 
queue manager checks the type 
against the type in operations to 
add entries to the queue and in 
operations to establish servers for 
the queue. Convergent reserves 

types 0-80, of which types 1, 2, and 
3 are assigned as follows: 
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Type Assignment 

1 Printer Spooler queue 

2 RJE queue 

3 Batch queue 

A sample queue index file is shown in Figure 15-2 
below. 


SpoolerA/ SpoolerAQueueEntryFile/l/l <RETURN> 
RJEBoston/RJEBostonQueueEntryFile/l/2 <RETURN> 
BatchCarol/BatchCarolQueueEntryFile/l/ 3 <RETURN> 


Figure 15-2. Sample Queue index File. 


The above example defines one queue entry file 
for each queue name. Each queue-oriented service 
generally requires more than one type of queue 
entry file. See Table 15-1 below. 



Table 15-1. 

Examples of Queue Entry Files. 

Server 

Process 

Type 

Number Required 

Batch manager 

Scheduling 

1 

per batch queue 



Control 

1 

per batch manager 



Status 

1 

per cluster 





configuration 

Printer 

spooler 

Scheduling 

1 

per print class 



Control 

1 

per printer 



Status 

1 

per cluster 





conf iguration 

RJE 


Transmit 

1 

per cluster 





configuration 



Receive 

1 

per cluster 





configuration 
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Client processes add entries to the scheduling 
queue entry files. In the case of RJE, entries 
are added to the transmit queue entry file and 
removed from the receive queue entry file. The 
control and status queue entry files are used 
internally by the server processes for control 
and status purposes. For further information on 
queue entry files required in the queue index 
file, see: 

o the Batch Manual for the batch manager, 

o the System Utilities Manual for the printer 

spooler, and 

o the 2780/3780 RJE Terminal Emulator Manual 

for the RJE. 


Installing the Queue Manager 

The queue manager is installed with the Install 
Queue Manager utility (see the System Utilities 
Manual ) . Typically, this is part of “a submit 
file or batch job control file that is executed 
when the system is bootstrapped. (Submit files 
are described in the Executive Manual 7 batch job 
control files in the Batch Manual . ) 

The queue manager can be installed either 

o in an extended system partition, in which 

case the queue manager can be removed only 
when the OS is reloaded (see the "System 
Service Management" section) , or 

o in a secondary application partition, in 

which case the queue manager can be removed 
with the TerminatePartitionTasks or Vacate- 
Partition operation (see the "Application 
Partition Management" section) . 


Queue Entry File 

A queue entry file contains information for a 
single type of processing such as spooled 
printing, batch processing, or RJE. 
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More than one type of queue entry file is 
generally required for each queue-oriented 
service (for example, scheduling, control, and 
status queue entry files are required for a 
printer spooler queue). (See Table 15-1 above.) 

The client process specifies the queue name when 
submitting a queue entry for processing. The 
queue entry is automatically placed in the 
appropriate queue entry file by the queue 
manager . 

When the queue manager is installed, it opens the 
queue entry files specified in the queue index 
file. If a queue entry file does not exist, it 
is created with an initial size of 30 entries. 

If a queue entry file has insufficient space for 
adding an entry, the queue manager expands that 
queue entry file by an increment sufficient to 
contain 30 entries. 


Queue Entry 


A queue entry is a formatted request for 
processing that is added to the specified queue 
entry file by client processes. Client and 
server processes communicate via fields within 
the queue entries located at fixed offsets known 
to both client and server processes. When a 
server process is available, it obtains a queue 
entry for processing. 

A queue entry is a number of contiguous 512-byte 
sectors in a queue file. Each queue entry 
consists of two parts: 

o The first 40 bytes of the queue entry are 
reserved for the queue manager and include 
control information (see "Queue Status Block" 
below) . 

o The remaining bytes are type-specific, that 
is, they are specific to the type of the 
queue (see "Sample Queue Entry" below). 
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CLIENT OPERATIONS 


A client process can add entries to queue entry- 
files, read the entries of a queue entry file 
(typically, to determine the sequence and status 
of entries), and delete specific entries from the 
queue entry file. 


Adding an Entry to a Queue 

A client process adds an entry to the specified 
queue entry file with the AddQueueEntry 

operation. The client process specifies 

information, including: 

o a queue name that must correspond to a queue 
name contained in the queue index file, 

o a priority level (0-9 with 0 the highest), at 
which the entry is queued, 

o a pointer to a buffer containing the type- 

specific portion of the queue entry, 

o an optional time specification for the 

earliest time the entry is serviced, and 

o an optional time interval for requeueing of 
the entry after its removal from the queue 
entry file. The time interval is added to 
the time specification for servicing the 
entry . 

Before adding a new entry to the queue entry 
file, the queue manager checks the number of 
active server processes. If no server processes 
are actively serving the queue, some client 
processes may not wish to queue a new entry. 

Reading Queue Entries 

A client process reads queue entries with the 
ReadNextQueueEntry operation for each entry to be 
read. ReadNextQueueEntry is typically used to 
list the contents of all entries by utilities 
such as the Spooler utility (see the "Printer 
Spooler Utilities Overview" in the System 
Utilities Manual ) . ~~ ~ 

The client process specifies the queue name, 
queue entry handle (see below), and pointers to 
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buffers to which the queue entry and Queue Status 
Block (see below) are returned. 


Queue Entry Handle 

A queue entry handle is a 32-bit integer that 
uniquely identifies a queue entry. The control 
portion of the queue entry (the first 40 bytes 
that are reserved for the queue manager) contains 
the queue entry handle of the logically following 
queue entry. 


Queue Status Block 

The MarkKeyedQueueEntry , MarkNextQueueEntry (see 
"Marking Queue Entries" below) , and ReadQueue- 
Entry operations take a parameter that is the 
memory address of a Queue Status Block. These 
operations use the Queue Status Block to report a 
queue entry's server user number, priority, and 
the buffers in which the queue entry handles for 
the queue entry and the logically following queue 
entry are stored. 

The format of the Queue Status Block is shown in 
Table 15-2 below. The Queue Status Block is part 
of the control portion of the queue entry (the 
first 40 bytes that are reserved for the queue 
manager) . 



Table 15-2. 

Queue Status Block. 



Size 

Offset 

Field 

(bytes ) 

0 

qehRet 

4 

4 

priority 

1 

5 

ServerUserNum 2 

7 

qehNextRet 

4 


where 

qehRet is the buffer in which the queue 

entry handle of the queue entry is 
stored . 
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priority is the priority (0-9, with 0 the 

highest) at which the queue entry is 
placed in the queue. 


serverUserNum 

is a 16-bit user number that 
uniquely identifies the server in 
the master workstation. If a server 
marks the entry OFFFFh, the entry is 
unmarked . 

qehNextRet is the buffer in which the queue 
entry handle of the logically 
following queue entry is stored. 


Removing an Entry 

A client process removes a specific queue entry 
from the queue with the RemoveKeyedQueueEntry 
operation. The queue entry is identified by one 
or two key fields . 

A key is a particular field or combination of 
fields in a data record upon which the lookup 
process is performed. The RemoveKeyedQueueEntry 
operation can specify that up to two key fields 
must match corresponding fields in the queue 
entry before the queue entry is removed. 
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SERVER OPERATIONS 


A server process can 

o establish itself as an active server for the 
specified queue(s), 

o mark and obtain queue entries for processing, 
and 

o unmark queue entries or remove itself as an 
active server. 


Establishing Servers 

A server process must establish itself as a 
server for a specific queue entry file with the 
EstablishQueueServer operation before it can 
service the queue. 

EstablishQueueServer enables the queue manager to 
keep a count of the number of servers servicing 
each queue entry file. The queue manager checks 
the count of servers before adding entries to a 
queue entry file. If no servers are active, a 
client process may not wish to queue a new 
entry . 


Marking Queue Entries 

The server process obtains a queue entry on which 
to operate with either of two operations: 

o the MarkNextQueuedEntry operation to specify 
the next available queue entry, or 

o the MarkKeyedQueueEntry operation to specify 
a specific queue entry. 

The queue manager marks the specified queue entry 
as being in use to prevent other server processes 
from operating on it. 

The marking operations prevents interference 
among multiple server processes servicing a 
single queue entry file. When a queue entry is 
marked, it is not returned in subsequent marking 
operations. 
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Unmarking Queue Entries 

Entries are reset to the unmarked (not in use) 
state when: 

o the queue manager is installed, 

o a server process terminates operation for any 
reason, including malfunction of a cluster 
workstation. The queue manager searches all 
queue entry files affected and resets any 
queue entries marked by server processes from 
the malfunctioning workstation. 

o a server process no longer wishes to service 
a queue entry file and issues a Terminate- 
QueueServer operation. The queue manager 
decrements the count of active servers for 
that queue and resets all entries previously 
marked by the terminating server. 

Sample Queue Entry 

Table 15-3 below shows a sample queue entry for 
printer spooler scheduling. The queue entry 
format can also be used for user-defined server 
processes. Queue entries must be large enough to 
accommodate the control portion of the queue 
entry (40 bytes that are reserved by the queue 
manager) . 


Table 15-3. Sample Queue Entry. 

(Type-Specific Portion for the Printer Spooler Scheduling Queue) 

Offset 

Field 

Size 
(bytes ) 

0 

fDeleteAfterProc 

1 

1 

cbSpoolerFileSpec 

1 

2 

SpoolerFileSpec 

91 

93 

cbFormName 

1 

94 

FormName 

12 

106 

cbWheelName 

1 

107 

WheelName 

12 

119 

cCopies 

2 

121 

bPrintMode 

1 

122 

fAlignForm 

1 

123 

fSecurityMode 

1 
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OPERATIONS: SERVICES 

Queue management operations are categorized by- 

user group below. 

Client Process Group 

AddQueueEntry adds an entry to the specified 

queue entry file for processing 
by the appropriate queue 
server . 

ReadKeyedQueueEntry 

obtains the first queue entry 
in the specified queue entry 
file with up to two key fields 
equal to the values specified, 
reads it into a buffer, and 
returns the Queue Status Block. 


ReadNextQueueEntry 

reads an entry from the 
specified queue entry file into 
a buffer and returns the queue 
entry handle of the next queue 
entry. 

RemoveKeyedQueueEntry 

locates an unmarked entry in 
the specified queue entry file 
with up to two key fields equal 
to the values specified and 
removes it from the queue entry 
file . 


Server process Group 

EstablishQueueServer 

establishes that a server 
process wishes to service the 
specified queue entry file. 

MarkKeyedQueueEntry 

locates the first unmarked 
entry in the specified queue 
entry file with up to two key 
fields equal to the values 
specified, marks it as being in 
use, reads it into a buffer, 
and returns a queue entry 
handle for use in a subsequent 
RemoveMarkedQueueEntry 
operation. 
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MarkNex tQueue Entry- 

reads the first unmarked entry 
in the specified queue entry 
file into a buffer, marks it as 
being in use, and returns a 
queue entry handle. Entries 
are marked in order of 
priority . 

RemoveMarkedQueueEntry 

removes a previously marked 
entry from the specified queue 
entry file. 

RewriteMarkedQueueEntry 

rewrites the specified marked 
queue entry with a new queue 
entry . 

TerminateQueueServer 

notifies the queue manager that 
a server process is no longer 
servicing the specified queue 
entry file. 

UnmarkQueueEntry resets the specified queue 

entry as unmarked (not in use). 
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AddQueueEntry 

Description 

The AddQueueEntry service is used by the client 

process to add a queue entry to the specified 

queue entry file for processing by the 

appropriate queue server. 

Procedural Interface 

AddQueueEntry (pbQueueName, cbQueueName , 

fQueuelfNoServer , priority, 
queueType, pEntry, sEntry, 
pDateTime, repeatTime): ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

fQueuelfNoServer 

is TRUE or FALSE. 

If fQueuelfNoServer is TRUE, the 
queue manager adds the entry to the 
specified queue entry file whether 
or not servers are active. 

If fQueuelfNoServer is FALSE, the 
queue manager returns status code 
908 ("Queue not served") when no 
servers are active for the specified 
queue entry file. 

priority is the priority (0-9, with 0 the 

highest) at which the entry is 
placed in the queue entry file. 

queueType is the type of the queue (an integer 
less than or equal to 255), which is 
used in a consistency check. The 
queue manager checks the type 
against the type in the queue index 
file . 

pEntry 

sEntry describe the buffer that contains 

the type-specific portion of the 
queue entry. 
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pDateTime is a pointer to the 32-bit date/time 

in Convergent format (described in 
the "Time Management" section) . It 
specifies the earliest time the 
queue entry is served. A 0 means 
the entry is served before an entry 
with a time specification. 

repeatTime specifies the repeating time 

interval in minutes (up to 65,335 
minutes) at which the queue entry is 
serviced. A 0 means no repetition 
occurs. (For example, to repeat the 
entry once a day, specify 1,440 
minutes; to repeat the entry once 
each week, specify 10,080 minutes.) 

Request Block 

sDateTime is always 4. 


Offset Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

3 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

137 

12 

fQueuelfNoServer 1 


13 

priority 

1 


14 

queueType 

2 


16 

repeatTime 

2 


18 

pbQueueName 

4 


22 

cbQueueName 

2 


24 

pEntry 

4 


28 

sEntry 

2 


30 

pDateTime 

4 


34 

sDateTime 

2 

4 
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EstablishQueueServer 


Description 


Procedural 


The EstablishQueueServer service is used by the 
server process to notify the queue manager that 
it wishes to service the specified queue entry 
file. A server process should issue Establish- 
QueueServer before any other operation to the 
queue manager. 

Interface 

EstablishQueueServer ( pbQueueName , cbQueueName, 

queueType , 

fUniqueServer ) : ErcType 


where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to the queue name specified in the 
queue index file. 

queueType is the type of the queue (an integer 
less than or equal to 255), which is 
used in a consistency check. The 
queue manager checks the type 
against the type in the queue index 
file. 


fUniqueServer 

is TRUE or FALSE. 

If fUniqueServer is TRUE, the 
requesting process intends to become 
the unique server of the specified 
queue. If servers already exist, 
the queue manager returns status 
code 914 ("Queue already served"). 
If the operation succeeds, it 
prevents other servers from being 
established for that queue. 

If fUniqueServer is FALSE, the 
requesting process does not intend 
to become the unique server of the 
specified queue. 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

146 

12 

queueType 

2 


14 

fUniqueServer 

1 


15 

reserved 

1 


16 

pbQueueName 

4 


20 

cbQueueName 

2 
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MarkKeyedQueueEntry 

Description 

The MarkKeyedQueueEntry service is used by the 
server process to obtain the first unmarked queue 
entry with up to two key fields equal to the 
values specified. MarkKeyedQueueEntry marks the 
queue entry as being in use, reads it into a 
buffer, and returns a queue entry handle by which 
the queue entry is identified in a subsequent 
RemoveMarkedQueueEntry operation . 

The byte count of at least one key field (either 
cbKeyl or cbKey2 ) must be nonzero. If only one 
is nonzero, only that key field is used in the 
search. If both are nonzero, both are used in 
the search. 

Each nonzero key field must match a specified sb 
string in the queue entry. In an sb string , the 
first byte contains the byte count of the string 
in binary. 

Procedural Interface 

MarkKeyedQueueEntry (pbQueueName , 

cbQueueName, pbKeyl, cbKeyl, 
oKeyl, pbKey2, cbKey2 , 
oKey2, pEntryRet, sEntryRet, 
pStatusBlock , 
sStatusBlock) : ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

pbKeyl 

cbKeyl describe a key field to be compared 

with an sb string located at an 
offset oKeyl in the queue entry. 

oKeyl is the offset of the sb string key 

field in the queue entry. The 
offset starts from byte 40 (the 
first byte of the type-specific 
portion of the queue entry) . 
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pbKey2 

cbKey2 


oKey2 


pEntryRet 
s Entry Ret 


pStatusBlock 

sStatusBlock 


describe a second key field to be 
compared with an sb string located 
at an offset oKey2 in the queue 
entry. 

is the offset of the second sb 
string key field in the queue 
entry. The offset starts from byte 
40 (the first byte of the type- 
specific portion of the queue 
entry) . 


describe the buffer into which the 
queue entry is read. 


describe the buffer into which the 
status block for the queue entry is 
returned . 


Queue Management 15-21 



Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

oKeyl 

2 

14 

oKey2 

2 

16 

pbQueueName 

4 

20 

cbQueueName 

2 

22 

pbKeyl 

4 

26 

cbKeyl 

2 

28 

pbKey2 

4 

32 

cbKey2 

2 

34 

pEntryRet 

4 

38 

sEntryRet 

2 

40 

pStatusBlock 

4 

44 

sStatusBlock 

2 
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MarkNextQueueEntry 

Description 


The MarkNextQueueEntry service is used by the 
server process to read the first unmarked entry 
from the specified queue entry file into a buffer 
for processing. Entries are marked in order of 
priority . 

MarkNextQueueEntry marks the entry as being in 
use and returns a queue entry handle by which the 
entry is identified in a subsequent RemoveMarked- 
QueueEntry operation. 


Procedural Interface 

MarkNextQueueEntry (pbQueueName , cbQueueName, 

f ReturnlfNoEntries , 
pEntryRet, sEntryRet, 
pStatusBlock , 
sStatusBlock) : ErcType 


where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

f ReturnlfNoEntries 

is TRUE or FALSE. 

If fReturnlfNoEntries is TRUE, the 
queue manager returns status code 
903 ("No entries available") unless 
an unmarked entry is queued. 

If fReturnlfNoEntries is FALSE, the 
queue manager responds to MarkNext- 
QueueEntry only when an unmarked 
entry is queued. 


pEntryRet 

sEntryRet describe the buffer into which the 
queue entry is read. 


pStatusBlock 

sStatusBlock describe the buffer into which the 
status block for the queue entry is 
returned . 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

2 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

141 

12 

fReturnlfNoEntr ies 1 


13 

reserved 

1 


14 

pbQueueName 

4 


18 

cbQueueName 

2 


20 

pEntryRet 

4 


24 

s Entry Ret 

2 


26 

pStatusBlock 

4 


30 

sStatusBlock 

2 
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Re adKeyedQueue Entry 

The ReadKeyedQueueEntry service is used by the 
client process to obtain the first queue entry 
with up to two key fields equal to the values 
specified. ReadKeyedQueueEntry reads the entry 
into a buffer and returns the Queue Status Block. 

The byte count of at least one key field (either 
cbKeyl or cbKey2) must be nonzero. If only one 
is nonzero, only that key field is used in the 
search. If both are nonzero, both are used in 
the search. 

Each nonzero key field must match a specified sb 
string in the queue entry. In an sb string , the 
first byte contains the byte count of the string 
in binary. 

Procedural Interface 

ReadKeyedQueueEntry (pbQueueName , 

cbQueueName, pbKeyl, cbKeyl, 
oKeyl, pbKey2, cbKey2 , 
oKey2, pEntryRet, sEntryRet, 
pStatusBlock , 
sStatusBlock) : ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file . 

pbKeyl 

cbKeyl describe a key field to be compared 

with an sb string located at an 
offset oKeyl in the queue entry. 

oKeyl is the offset of the sb string key 

field in the queue entry. The 
offset starts from byte 40 (the 
first byte of the type-specific 
portion of the queue entry) . 

pbKey2 

cbKey2 describe a second key field to be 

compared with an sb string located 
at an offset oKey2 in the queue 
entry. 
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oKey2 


is the offset of the second sb 
string key field in the queue 
entry. The offset starts from byte 
40 (the first byte of the type- 
specific portion of the queue 
entry) . 

pEntryRet 

sEntryRet describe the buffer into which the 
queue entry is read. 

pStatusBlock 

sStatusBlock 

describe the buffer into which the 
status block for the queue entry is 
returned . 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

3 

3 

nRespPbCb 

1 

2 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

140 

12 

oKeyl 

2 


14 

oKey2 

2 


16 

pbQueueName 

4 


20 

cbQueueName 

2 


22 

pbKeyl 

4 


26 

cbKeyl 

2 


28 

pbKey2 

4 


32 

cbKey2 

2 


34 

pEntryRet 

4 


38 

sEntryRet 

2 


40 

pStatusBlock 

4 


44 

sStatusBlock 

2 
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ReadNextQueueEntry 

Description 


I 


The ReadNextQueueEntry service is used by the I 

client process to obtain a list of queue 
entries. ReadNextQueueEntry reads an entry from 
the specified queue entry file into a buffer and 
returns the Queue Status Block, which contains 
the queue entry handle of the next entry in the 
queue. The entry data returned begins with byte 
40 (first byte of the type-specific portion) of 
the first sector of the queue entry. 

If another client process removes the next queue 
entry before it is read, status code 904 ("Entry 
deleted") is returned on any attempt to read that 
entry . 

Procedural Interface 

ReadNextQueueEntry ( pbQueueName , cbQueueName, I 

qeh, pEntryRet, sEntryRet, 
pStatusBlock, 
sStatusBlock) : ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

qeh is the 32-bit queue entry handle 

returned from a previous MarkKeyed- 
QueueEntry or MarkNextQueueEntry 
operation. A 0 indicates the first 
entry in the queue . 

pEntryRet 

sEntryRet describe the buffer into which the 
queue entry is read. 


pStatusBlock 

sStatusBlock describe the buffer into which the 
status block for the queue entry is 
returned . 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

2 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

140 

12 

qeh 

4 


16 

pbQueueName 

4 


20 

cbQueueName 

2 


22 

pEntryRet 

4 


26 

sEntryRet 

2 


28 

pStatusBlock 

4 


32 

sStatusBlock 

2 
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RemoveKeyedQueueEntry 

Description 

The RemoveKeyedQueueEntry service is used by the 
client process to locate an unmarked entry in the 
specified queue entry file with up to two key 
fields equal to the values specified and to 
remove the entry from the queue entry file. 

The byte count of at least one key field (either 
cbKeyl or cbKey2 ) must be nonzero. If only one 
is nonzero, only that key field is used in the 
search. If both are nonzero, both are used in 
the search. 

Each nonzero key field must match a specified sb 
string in the queue entry. In an sb string , the 
first byte contains the byte count of the string 
in binary. 

Procedural Interface 

RemoveKeyedQueueEntry (pbQueueName , cbQueueName, 

pbKeyl, cbKeyl, oKeyl, 
pbKey2 , cbKey2 , 
oKey2 ) : ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

pbKeyl 

cbKeyl describe a key field to be compared 

with an sb string located at an 
offset oKeyl in the queue entry. 

oKeyl is the offset of the sb string key 

field in the queue entry. The 
offset starts from byte 40 (the 
first byte of the type-specific 
portion of the queue entry) . 

pbKey2 

cbKey2 describe a second key field to be 

compared with an sb string located 
at an offset oKey2 in the queue 
entry. 
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oKey2 


is the offset of the second sb 
string key field in the queue 
entry. The offset starts from byte 
40 (the first byte of the type- 
specific portion of the queue 
entry) . 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

3 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

138 

12 

oKeyl 

2 


14 

oKey2 

2 


16 

pbQueName 

4 


20 

cbQueName 

2 


22 

pbKeyl 

4 


26 

cbKeyl 

2 


28 

pbKey2 

4 


32 

cbKey2 

2 
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RemoveMarkedQueueEntry 

Description 

The RemoveMarkedQueueEntry service is used by the 
server process to remove a previously marked 
entry from the specified queue entry file. The 
queue entry to be removed is identified by a 
queue entry handle previously returned from a 
MarkKeyedQueueEntry or MarkNextQueueEntry 

operation. 

Procedural Interface 

RemoveMarkedQueueEntry (pbQueueName, cbQueueName, 

qeh ) : ErcType 


where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

qeh is the 32-bit queue entry handle 

returned from a previous MarkKeyed- 
QueueEntry or MarkNextQueueEntry 
operation . 

Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

143 

12 

qeh 

4 


16 

pbQueueName 

4 


20 

cbQueueName 

2 
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RewriteMarkedQueueEntry 

Description 

The RewriteMarkedQueueEntry service is used by 
the server process to rewrite the specified queue 
entry with a new entry. RewriteMarkedQueueEntry 
can be used to update a field contained in a 
queue entry. The entry to be overwritten is 
identified by a queue entry handle returned from 
a previous MarkKeyedQueueEntry or 

MarkNextQueueEntry operation. 

Procedural Interface 

RewriteMarkedQueueEntry (pbQueueName, 

cbQueueName, qeh, 
pEntry, sEntry): ErcType 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

qeh is the 32 -bit queue entry handle 

returned from a previous MarkKeyed- 
QueueEntry or MarkNextQueueEntry 
operation . 


pEntry 

sEntry describe the buffer into which the 

type-specific portion of the queue 
entry is read. 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

145 

12 

qeh 

4 


16 

pbQueueName 

4 


20 

cbQueueName 

2 


22 

pEntry 

4 


26 

sEntry 

2 
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TerminateQueueServer 


Description 


The TerminateQueueServer service is used by the 
server process to notify the queue manager that 
the server process is no longer servicing the 
specified queue entry file. The server process 
should use TerminateQueueServer when it 
terminates under normal circumstances. 

TerminateQueueServer unmarks any queue entries 
that were marked by the terminating server 
process . 


Procedural Interface 

TerminateQueueServer ( pbQueueName , 

cbQueName): ErcType 


where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

147 

12 

pbQueueName 

4 


16 

cbQueueName 

2 
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UnmarkQueueEntry 

Description 


The UnmarkQueueEntry service is used by the 
server process to reset the specified queue entry 
as being unmarked (not in use). The queue entry 
to be unmarked is identified by a queue entry 
handle returned from a previous 

MarkKeyedQueueEntry or MarkNextQueueEntry 

operation . 

Procedural Interface 

UnmarkQueueEntry (pbQueueName, cbQueueName, 

qeh): Ere Type 

where 

pbQueueName 

cbQueueName describe a queue name corresponding 
to a queue name specified in the 
queue index file. 

qeh is the 32-bit queue entry handle 

returned from a previous MarkKeyed- 
QueueEntry or MarkNextQueueEntry 
operation. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

144 

12 

qeh 

4 


16 

pbQueueName 

4 


20 

cbQueueName 

2 
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data records, the number of keys, and the type of 
each key are specified when an ISAM data set is 
created. An ISAM data set consists of two 
files: an index file and a data store file. 


Hybrid Patterns of Access 

In the following sections, a file is often 
referred to as a SAM file, meaning that access to 
the file is primarily by means of the Sequential 
Access Method. The terms RSAM file, DAM file, or 
ISAM data store file are used similarly. 

This usage, while convenient, is oversimpli- 
fied: any file created with RSAM, DAM, or ISAM 

can be physically viewed as unstructured and 
accessed using SAM. Similarly, any file of 
records created with DAM or ISAM can be 

physically accessed using RSAM (that is, treating 
fixed-length records as a special case of 

variable-length records). Finally, an ISAM data 
store file contains fixed-length records and 
therefore can be accessed using DAM. 

Although all these hybrid patterns of access are 
possible, they are not all advisable. For 
example, reading a DAM file with SAM fetches 
control bytes along with the DAM record bytes? 
interpreting these requires special knowledge. 

As a second example, an ISAM data store file has 
an associated index file that must be updated in 
a complex way when the data store file is 
modified. If the data store file is modified 
using ISAM, this is done automatically. If the 
data store file is updated otherwise, the 

integrity of the ISAM data set can easily be 

destroyed . 

The hybrid patterns of access listed below are 
both useful and safe: 

o Use of RSAM to read, write, or append to a 
DAM-created file. (However, if, following a 
write or append to such a file, there are 

records of different lengths, then the file 
is subsequently accessible only with RSAM, 
not with DAM . ) 

o Use of DAM to read or modify an RSAM-created 
file in which all records have the same 

length. 
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o 


Use of RSAM or DAM to read an ISAM-created 
file as though it were an unkeyed DAM file, 
that is, with the records accessed according 
to their physical ordering. 

Modifying and Reading Data Files 

The Maintain File utility can modify and/or read 
RSAM and DAM data files. Maintain File can: 

o verify the file structure, 

o remove malformed records, 

o remove deleted records, and 

o optionally write a log of the verification of 
the file structure to a file. (The log 
always appears on the video display . ) 

Maintain File is also used with the ISAM 
Reorganize utility. (See the ISAM Manual for 
more information.) 

Maintain File is described in the System 
Utilities Manual. 
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CONCEPTS 


RSAM and DAM files and ISAM data store files 
contain standard record headers, record trailers, 
and file headers. 


Standard Record Header 

The offsets described in Table 16-1 below are 
relative to the beginning of a physical record. 
A physical record consists of the record header, 
the record data, and the record trailer stored in 
contiguous bytes. 
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Table 16-1. Format of a Standard Record Header. 


Offset 

Field 

Size 
(bytes ) 

Description 

0 

qURI 

4 

Universal Record 
Identifier. lfa 
of the physical 
record . 

4 

sPhy Record 

2 

Size of the phy- 
sical record, in- 
cluding the record 
header and 
trailer . 

6 

bCheck 

1 

Status byte that 
has the following 
meaning : 




0 

Record does not 
logically exist. 




1 

Record previous- 
ly existed but 
was deleted. 




2-15 

Reserved . 




16-255 

Record logically 
exists. bCheck 
is set to 16 the 
first time it is 
written and is 
incremented on 
each subsequent 
write. bCheck 
recycles to 16 
on overflow. 






Standard Record Trailer 


The offsets described in Table 16-2 below are 
relative to the beginning of a physical record. 
sRecord is the logical record size. 


Table 16-2. Format of a Standard Record Trailer. 


Size 

Offset Field (bytes ) Description 

sRecord+7 bDoubleCheck 1 Copy of 

bCheck. If 
bCheck and 
bDoubleCheck 
are not 
equal, the 
record is 
malformed. 


Standard File Header 

The offsets described in Table 16-3 below are 
relative to the beginning of the file. A 
standard file header occupies an integral number 
of sectors at the start of the file. The header 
consists of information common to all standard 
access methods followed by information unique to 
the particular access method. If no access- 
method-dependent information is present, the 
first physical record is located at the beginning 
of the second file sector. 
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Table 16-3. Format of a Standard File Header. (Page 2 of 2) 







OPERATIONS : PROCEDURES 


The File Access Methods provide the operation 
listed below. 

GetStamFileHeader 

copies the file header of an 
RSAM, DAM, or ISAM file into 
the specified area. 


16-10 CTOS” Operating System Manual 



GetStamFileHeader 


Description 

The GetStamFileHeader procedure copies the file 
header of an RSAM, DAM, or ISAM file into the 
specified area. The format of the standard file 
header is described in the section of that name 
above . 

Procedural Interface 

GetStamFileHeader (pbFileSpec, cbFileSpec, 

pbPas sword, cbPas sword, 
pFileHeaderRet ) : ErcType 

where 

pbFileSpec 

cbFileSpec describe a character string 

specifying the name of the file 

whose header is to be read. 

pbPassword 

cbPassword describe a character string 

specifying the password authorizing 
the requested file access. 

pFileHeaderRet 

describes the memory area into which 
the file header is copied. The 
memory area must be at least 512 
bytes long and word aligned. | 

Request Block 

GetStamFileHeader is an object module procedure. 
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17 SEQUENTIAL ACCESS METHOD 


OVERVIEW 


Th e Sequential Access Method (SAM) provides 
device-independent access to real devices (such 
as the video display, printer, files, and 
keyboard) by emulating a conceptual, sequential, 
character-oriented device. 

SAM augments the device-dependent CTOS operations 
that are specific to each kind of peripheral 
device available on a workstation. These 
operations maximize efficiency and provide access 
to all features of the peripheral device 
hardware. However, in many cases, maximum 
efficiency and specialized features are not as 
important as device independence. 

Consider a program such as a compiler. It is 
advantageous if a compiler can accept its source 
data from either the keyboard or a file and can 
direct its listing to the video display, a 
printer, or a file. 

Programs of this type characterize their input 
and output as sequences of characters. Selection 
at execution time of input/output devices can be 
accomplished for such programs by allowing each 
type of real device or file to emulate a 
conceptual device that accepts or supplies any 
number of characters, but only in sequence. 

To retain a large degree of device independence 
and yet allow access to a few of the most 
important device-dependent features, extensions 
to SAM provide device-dependent operations. 

For some application systems, not all of the 
devices supported by SAM are used. For example, 
an application system can use SAM only to obtain 
keyboard input and to display text on the video 
display. It is possible to customize the 
selection of device-dependent SAM object modules 
that are linked with an application system. This 
customization, S AMGen , is described in the System 
Programmer 1 s Guxde . 
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CONCEPTS 


Byte Streams 


The Sequential Access Method (SAM) uses real 
devices such as the video display, printer, 
files, and keyboard to emulate a conceptual, 
sequential, character-oriented device known as a 
byte stream. 

A byt e stream is a readable (input) or writable 
(output) sequence of 8-bit bytes. An input byte 
stream can be read until either the reader 
chooses to stop reading or until it receives 
status code 1 ("End of file"). An output byte 
stream can be written until the writer chooses to 
stop writing. (Of course there are physical 
limitations: a file could expand to fill all 

available disk storage, for example.) 

A Byte Stream Work Area (BSWA) is a 130-byte 
memory work area for the exclusive use of SAM 
procedures. Any number of byte streams can be 
open concurrently, using separate BSWAs . 

SAM consists of object module procedures 
contained in the standard CTOS library. 


Using a Byte Stream 

The first step in using a byte stream is to call 
the OpenByteStream operation. The user supplies 
the specification of the device/file, a password 
if appropriate, the mode (indicating whether 
input or output is desired), and the address of 
the 130-byte BSWA. When calling other operations 
such as ReadBsRecord, WriteBsRecord , and 
CloseByteStream, the user supplies the address of 
the same BSWA. 


Predefined Byte Streams for Video and Keyboard 

There are two predefined and already opened Byte 
Stream Work Areas (bsVid for video frame 0 and 
bsKbd for the keyboard) . These special BSWAs are 
defined in SAM standard object modules. Because 
these BSWAs are already opened, it is not 
necessary (nor allowed) to specify them as 
arguments to OpenByteStream or CloseByteStream. 
In secondary application partitions, these 
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special BSWAs access System Output (SysOut) and 
System Input (Sysln) facilities. (See the Batch 
Manual . ) 


Device/File Specifications 

The device/file specification in the 

OpenByteStream operation is any of the following: 

{node} [ volname] <dirname> filename 

File identified by its full file 
specification. Abbreviated specifi- 
cations are also allowed. See the 
"File Management" section. 

[Lpt] & [volname] <dirname> filename 

Centronics-compatible 
connected to the parallel 
port. See the "Printer 
Management" section. 

&[ volname] <dirname> filename de- 

scribes an optional configuration 
file containing the printer 
characteristics. A default 

configuration file is used if none 
is specified. See the Create 

Configuration File utility in the 
System Utilities Manual for details 
about the configuration file. 

[Ptr]n&[volname] <dirname> filename 

RS-232C-compatible printer. n is A 
or B to indicate the SIO 
communications channel to which the 
printer is connected. See the 
"Printer Spooler Utilities Overview" 
in the System Utilities Manual . 

Se[ volname] <dirname> filename de- 

scribes an optional configuration 
file containing the printer 
characteristics. A default 

configuration file is used if none 
is specified. See the Create 

Configuration File utility in the 
System Utilities Manual for details 
about the configuration file. 


printer 

printer 

Spooler 
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{node} [queuename] reportname 

Spooled Printer. 

The queue name is the name of the 
scheduling queue associated with the 
printer spooler. [Spl] is the 
default name of the first spooled 
printer . 

The report name is a text string of 
up to 12 characters that is included 
in the Spooler utility's status 
display. 

See the "Printer Spooler Utilities 
Overview" in the System Utilities 
Manual . 

[Kbd] 

Keyboard. This also includes the 
System Input (Sysln) facility used 
for submit files and batch jobs. 
See the "Keyboard Management" 
section in this Manual for submit 
files and the Batch Manual for batch 
jobs . 

[Comm]_n&[ volname] <dirname> filename 

~~ Communications Channel n_ (A or B) of 
the SIO communications controller. 

&[ volname] <dirname> filename de- 
scribes an optional configuration 
file containing the communications 
characteristics. A default 
configuration file is used if none 
is specified. See the Create 
Configuration File utility in the 
System Utilities Manual for details 
about the configuration file. 

[X25]n_&[ volname] <dirname> filename 

X.25 virtual circuit. n_ is a 
network identification which 
currently must be zero. 

&[ volname] <dirname> filename describe 
an optional configuration file 
containing the circuit 
characteristics. See the X.25 
Network Gateway Manual . 
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[Nul] 


Null device. Input operations 
always return status code 1 ("End of 
file"). Output operations discard 
all output but return status code 0 
("OK") . 


[vid] 

Video frame 0. The frame must be 
established in advance using the 
Video Display Management or the 
Convergent Executive. (See the 

"Video Display Management" 

section.) In secondary application 
partitions, [Vid] refers to the 
System Output (SysOut) facility. 
(See the Batch Manual . ) 

[Vid]ji 

Video frame n. 


Customizing SAM 


SAM provides device-independent access to a 
variety of devices. The code that implements SAM 
is divided into a device-independent portion and 
several device-dependent portions, one for each 
kind of device that is supported. 

The default SAM supports these devices: 

o disk, 

o parallel printer, 
o spooled printer, 
o keyboard, 
o null, and 

o video display. 

For further flexibility, SAM can be customized by 
a SAM generation ( SAMGen ) that is similar to a 
system build. This allows: 

o reduction of the memory needed by an 
application system by eliminating unneeded 
device support. 
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o inclusion of support for communications and 
serial (RS-232C) printers, and 

o inclusion of user-written device-specific SAM 
object modules. 

See the System Programmer 1 s Guide for information 
on SAMGen. 


File Byte Streams 

A f ile byte stream is a byte stream that uses a 
file on disk. The standard operations of SAM are 
augmented by two operations that allow random 
access to files: GetBsLfa and SetBsLfa. These 
device-dependent operations are only available 
for file byte streams and return status code 7 
("Not implemented") if attempted on other byte 
streams . 


Printer Byte Streams 

A printer byte stream is a byte stream that 
performs direct printing. Direct printing 
transfers text directly from application system 
memory to the specified parallel or serial 
printer interface of the workstation on which the 
application system is executing. A printer byte 
stream cannot be used to access a printer 
assigned to the printer spooler. 

The selected configuration file determines the 
printer characteristics. (See the Create 
Configuration File utility in the System 
Utilities Manual . ) For example, the 
configuration file controls whether a printer 
byte stream suspends execution of the client 
process until the workstation operator corrects a 
condition requiring manual intervention or 
reports it to the calling process. 

Normally printer byte streams change tab and end- 
of-line characters to the form expected by the 
printer. For example. Convergent RETURNS (code 
OAh) can be transformed to carriage 
return/linefeed combinations for some printers, 
or just to carriage returns (code ODh) or 
linefeeds (code OAh) for others. Tab characters 
can be transformed to spaces for printers without 
mechanical tabs. These transformations are 
controlled by the selected configuration file. 
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Printing Modes 


Any of three printing modes can be specified with 
the SetlmageMode operation: normal, image, or 
binary. SetlmageMode sets the printing mode any 
time following the opening of the printer byte 
stream. This differs from the effect of 
SetlmageMode when used with spooler byte streams 
( see below) . 

For compatibility between spooled and direct 
printing, SetlmageMode should be used before the 
first WriteBsRecord or WriteByte operation. 

Normal mode converts tabs into spaces and 
converts end-of-line characters to device- 
dependent codes. 

Image mode and binary mode perform no code # 
conversion. 

Binary mode does not print the banner page, send 
any extra code not in the file to the printer, 
nor does it recognize the escape sequences. 


Spooler Byte Streams 

See the "Printer Spooler Utilities Overview" in 
the System Utilities Manual before using a 
spooler byte stream and for information on 
printer spooler escape sequences. 

A spooler byte stream automatically creates a 
uniquely named disk file for temporary text 
storage. It then transfers the text to the disk 
file and expands the disk file as necessary. 
When the spooler byte stream is closed, a request 
is queued by the printer spooler to the queue 
manager to print the disk file and delete it 
after it is printed. This is spooled printing . 

Normally, spooler byte streams change tab and 
end-of-line characters to the form expected by 
the printer. For example. Convergent RETURNS 
(code OAh) can be transformed to carriage 
return/ linefeed combinations for some printers, 
or just to carriage returns (code ODh) or 
linefeeds (code OAh) for others. Tab characters 
can be transformed to spaces for printers without 
mechanical tabs. These transformations are 
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controlled by the selected configuration file. 
(See the Create Configuration File utility in the 
System Utilities Manual . ) 


Printing Modes 


Any of three printing modes can be set with the 
SetlmageMode operation: normal, image, or 
binary. SetlmageMode sets the printing mode only 
if it is called immediately following the opening 
of the spooler byte stream. This differs from 
the effect of SetlmageMode when used with printer 
byte streams (see above). 

For compatibility between spooled and direct 
printing, SetlmageMode should be used before the 
first WriteBsRecord or WriteByte operation. 

Normal mode prints the banner page between files, 
converts tabs into spaces, converts end-of-line 
characters to device-dependent codes, and 
recognizes the escape sequences for manual 
intervention. (See the "Printer Spooler 
Utilities Overview" in the System Utilities 
Manual for information on banner pages.) 

Image mode prints the banner page between files 
and recognizes the escape sequences, but performs 
no code conversion. 

Binary mode does not print the banner, send any 
extra code not in the file to the printer, nor 
does it recognize the escape sequences. 


Keyboard Byte Streams 

A keyboard byte stream is a byte stream that uses 
the keyboard. The function provided is 

equivalent to the use of the ReadKbd operation in 
character mode. (See the "Keyboard Management" 
section.) The keyboard byte stream does not 
support unencoded keyboard mode. 

To support device-independence, keyboard byte 
streams return status code 1 ("End of file") when 
the FINISH (ASCII value 7) key is pressed, and I 
status code 4 ( "Operator intervention" ) when the 
CANCEL (ASCII value 4) key is pressed. I 

For applications executing under control of the 
batch manager in secondary application 
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partitions, keyboard input is received from a 
System Input (Sysln) facility. (See the Batch 
Manual . ) 

See the "Keyboard Management" section for 
information on the submit facility and submit 
file escape sequences. 


Communications Byte Streams 

A communications byte stream is a byte stream 
that uses a communications channel. 
Communications byte streams provide support for 
the two communications channels of the standard 
SIO communications controller. Operation is in 
asynchronous full-duplex mode without explicit 
modem control. Unlike other byte streams, 
communications byte streams permit both input and 
output to be directed to the same open byte 
stream (that is, the same BSWA) . Only one byte 
stream can be opened for each communications 
channel of the SIO. 

The selected configuration file determines the 
communications characteristics. (See the Create 
Configuration File utility in the System 
Utilities Manual . ) 

Normally, communications byte streams strip null 
(OOh) and delete (7Fh) characters from the stream 
of received data characters. Image mode (set 
with the SetlmageMode operation) specifies that 
communications byte streams pass all incoming 
characters to the client process exactly as 
received . 


X.25 Byte Streams 

An X.25 byte stream is a byte stream that enables 
data transmission via the X.25 Network Gateway. 
(See the X.25 Network Gateway Manual . ) 

Each open X.25 byte stream corresponds to a 
virtual circuit that is initiated when the byte 
stream is opened, and cleared when the byte 
stream is closed. Setting up and clearing of the 
virtual circuit is controlled through the use of 
a configuration file. 
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Video Byte Streams 


A video byte stream is a byte stream tbat uses 
the video display. The standard operations of 
SAM are augmented by: 

o Special interpretation of certain characters. 

o Multibyte escape sequences. The multibyte 

escape sequences (beginning with the 
character OFFh) can be used to control the 
special video capabilities of the Convergent 
workstations . 

o One device-dependent operation. The 

QueryVidBs operation returns information 
about video byte streams. (See the 

description of that operation below.) 

For applications executing under control of the 
batch manager in secondary application 
partitions, video output is redirected to a 
System Output (SysOut) facility. (See the Batch 
Manual . ) 

See the "Video Management" section for 
information on other ways to control the video 
subsystem . 

Special Characters in Video Byte Streams 

The characters specially interpreted by video 
byte streams are described in Table 17-1 below. 
Note that a multibyte escape sequence (see the 
"Miscellaneous Functions" section below) is 
available that disables all these special 
interpretations except OFFh. 
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Table 17-1. 

Interpretation of Special Characters by Video Byte Streams. 
(Page 1 of 2) 

Hexa- 

decimal 

Value 

Key 

Video Byte Stream 
Interpretation 

Olh 

up arrow 

Move the cursor up one 
line. If the cursor is 
in the top line of the 
frame, reposition it to 
the bottom line. 

07h 

CANCEL 

Activate audio alarm for 
one-half second. 

08h 

BACKSPACE 

Backspace one character 
(with wraparound) and 
blank that character. 

09h 

TAB 

Tab to next multiple of 


eight columns. For ex- 
ample, if the cursor is 
in columns 0-7, it moves 
to column 8; if it is in 
columns 8-15, it moves to 
column 16. 

OAh RETURN Move to first column of 

next line; scroll if nec- 
essary. 

OBh down arrow Move the cursor down one 

line. If the cursor is 
in the bottom line of the 
frame, reposition it to 
the top line . 

OCh NEXT PAGE Blank the frame and posi- 

tion the cursor in its 
upper left corner. 

ODh BOUND Ignored. 
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Table 17-1. 

Interpretation of Special Characters by Video Byte Streams. 
(Page 2 of 2) 

Hexa- 


decimal 

Video Byte Stream 

Value 

Key Interpretation 

OEh 

left arrow Move the cursor left one 

character position. If 
the cursor is in the 
first column of the 
frame, reposition it to 
the last column. 

12h 

right arrow Move the cursor right one 
character position. If 
the cursor is in the last 
column of the frame, re- 
position it to the first 
column . 

OFFh 

CODE-DELETE Begin multibyte escape 
sequence . 


Multibyte Escape Sequences 

Multibyte escape sequences can: 

o control screen attributes, 

o control character attributes, 

o control scrolling and cursor positioning, 

o dynamically redirect a video byte stream, 

o automatically pause between full frames of 
text, and 

o perform various other miscellaneous 
functions . 

(Note that where the escape sequences include 
alphabetic characters, upper- and lowercase are 
equivalent . ) 
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Controlling Screen Attributes. Screen attributes 
can be controlled with these four multibyte 
escape sequences. Each of the 3-byte sequences 
below begins with the escape byte OFFh and 
continues with a pair of characters represented 
by the specified 8-bit ASCII character codes. 


Sequence 


Effect 


OFFh, 

•H* , 

'N' 

Turn on the screen 
bright attribute. 

half- 

OFFh, 

•H' , 

i p i 

Turn off the screen half- 
bright attribute. 

OFFh, 

•R’ , 

1 N ' 

Turn on the screen 
video attribute. 

reverse 

OFFh, 

'R' , 

■ pi 

Turn off the screen 
video attribute. 

reverse 


Controlling Character Attributes. Character 
attributes can be controlled with these multibyte 
escape sequences. 


Sequence 


Effect 


OFFh, 'A', mode Set the attribute for sub- 
sequent characters sent to 
the frame according to mode , 
where mode is a single ASCII 
character defined as fol- 
lows : 


Mode 

Blink 

Reverse 

Underline 

Half-bright 

'A' 

no 

no 

no 

no 

' B' 

no 

no 

no 

yes 

■C' 

no 

no 

yes 

no 

' D' 

no 

no 

yes 

yes 

' E ' 

no 

yes 

no 

no 

i p i 

no 

yes 

no 

yes 

'G' 

no 

yes 

yes 

no 

'H' 

no 

yes 

yes 

yes 

' I ' 

yes 

no 

no 

no 

' J* 

yes 

no 

no 

yes 

•K’ 

yes 

no 

yes 

no 

'L' 

yes 

no 

yes 

yes 

*M' 

yes 

yes 

no 

no 

'N* 

yes 

yes 

no 

yes 

'O' 

yes 

yes 

yes 

no 

■ p' 

yes 

yes 

yes 

yes 
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OFFh, 1 A ' f 


’ Z' Enable a mode where writing 

a character to a character 
position does not change the 
character attributes of that 
character position. 


Controlling Scrolling and Cursor Positioning. 
Characters are normally written to the frame 
sequentially, with the cursor advancing one 
character position at a time, from left to right 
and top to bottom. A cursor is normally 
displayed at the character position where the 
next character will be displayed. Text is 
automatically scrolled each time a character is 
written to the lower right corner of a frame. 
When such a scroll occurs, the entire contents of 
the frame scroll up one line, and the contents of 
the previous top line of the frame disappear. 

The following escape sequences directly control 
both scrolling and cursor positioning. 


Sequence Effect 

OFFh, 'C', x_, X Position the cursor at 

column 21 line y_ 

where x_ and y^ are 
single bytes contain- 
ing (in binary) the 
column and line num- 
bers. A value of OFFh 
for x or y_ specifies, 
respectively, the last 
column or line of the 
frame . 


OFFh, 'S', f, 1, c, 'D 


Scroll down a portion 
of the frame. The 
portion begins at line 
_f(irst) and extends 
down to, but not in- 
cluding, line _l_(ast) . 
It is scrolled down by 
c lines and the top c_ 
lines of the scrolled 
area are filled with 
the blank character 
recorded in the bSpace 
field of the Video 
Control Block. f_, _1_, 
and c are single bytes 
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Sequence Effect 

containing binary num- 
bers. A value of OFFh 
for f_ or 1_ specifies 
an imaginary line just 
below the bottom of 
the frame . 


OFFh, 

'S' , 

f_, 1_, c_, 'U' 

Scroll up a portion of 
the frame. 

OFFh, 

'V' , 

'N' 

Make the cursor vis- 
ible . 

OFFh , 

'V' , 

i p i 

Make the cursor invis- 
ible . 


Dynamically Redirecting a Video Byte Stream. 
When a video byte stream is opened, it is 
designated as directed to one of the frames. 
However, it is possible to dynamically redirect a 
video byte stream. 

Sequence Effect 

OFFh, 'X', Redirect this video byte 

stream to frame i_ where i_ is 
a single byte containing (in 
binary) the number of the 
required frame . 

An independent cursor position is recorded for 
each frame. The position within frame _i_ is 

restored automatically when a video byte stream 
is redirected to frame i. 


Automatically Pausing Between Full Frames of 
Text. Automatic pausing between full frames of 
text can be controlled through multibyte escape 
sequences. When this pause facility is enabled, 
and further output to the frame would cause text 
to be scrolled off the top of the frame, the 
message : 

Press NEXT PAGE to continue 

is displayed on the last line of the frame. At 
this point, if the user presses NEXT PAGE, output 
continues for another full frame of text. If the 
user presses CANCEL, status code 4 ("Operator 
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intervention") is returned to the calling 
process. If the user presses FINISH, status code 
1 ("End of file") is returned to the calling 
process. If the user presses any other key, the 
audio alarm is momentarily activated. 

Since the automatic pause facility reads 

characters from the keyboard (using the 
ReadKbdDirect operation; see the "Keyboard 
Management" section) , there is a potential for 
interaction with the client process's use of the 
keyboard. A single process that uses a keyboard 
byte stream and one or more video byte streams 
will operate correctly. 

A more complex environment may require the use of 
application-specific logic to control pauses in 
scrolling. Contraindications to automatic 

pausing are: 

o use of the unencoded keyboard mode, 

o keyboard input performed by a different 
process from the one using video byte 
streams, and 

o keyboard input initiated by the use of the 
Request primitive and not immediately 
followed by the Wait primitive. 


Sequence 

Effect 


OFFh, 

'P' , 'N* 

Turn on the pause 

facility. 

OFFh, 

, p , , • F • 

Turn off the pause 

facility. 


Miscellaneous Functions. The following multibyte 
escape sequences perform the specified 
miscellaneous functions. 

Sequence Effect 

OFFh, 'L', 'N' Enable literal mode, 

with special character 
interpretation sup- 
pressed (except for the 
escape character OFFh) . 
(See Table 17-1 above.) 
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Sequence 


OFFh, ’L', 'F* 

OFFh , ' E 1 , 'L' 


Effect 


For example, in literal 
mode, the character 
code 08h displays a 
visible backspace sym- 
bol rather than per- 
forming the backspace 
function . 

Disable literal mode. 

Erase to the end of the 
current line of the 
frame. That is, set 
the characters to the 
blank character re- 
corded in the bSpace 
field of the Video 
Control Block and turn 
off all attributes. 


OFFh, ' E' , 1 F* 

OFFh , ' F ' , char , x_, 

w, h 


Erase to the end of the 
current frame. 

Fill an entire rec- 
tangle of the current 
frame with a single 
character given by the 
single byte char . The 
rectangle is specified 
by four 1-byte binary 
numbers: the column 

and line of the upper 
left corner (x and y) , 
and the w£3th and 
height (w^ and h) of the 
rectangle. A value of 
OFFh for x_ or y_ spec- 
ifies, respectively, 
the last column or line 
of the frame. A value 
of OFFh for w_ or h_ 
specifies, respective- 
ly, the remaining width 
or height of the frame. 
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Sequence 


Effect 


OFFh, 'I', led, ' N' Turn on an LED indi- 

cator on the keyboard 
according to the fol- 
lowing table : 


LED 

Key 

•1' 

fl 

’2' 

f 2 

’3' 

f 3 

'8' 

f 8 

'9' 

f9 

'O' 

flO 

1 rp ! 

OVERTYPE 


OFFh, 'I', led , * F* Turn off an LED indi- 

cator on the keyboard 
according to the table 
immediately above . 

OFFh, OFFh Display a single cross- 

hatch bar-chart char- 
acter. The cross-hatch 
bar-chart character has 
an 8-bit representation 
of OFFh (255) and thus 
cannot be displayed in 
any other way . 
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OPERATIONS : PROCEDURES 


Sequential Access Method operations are 
categorized by function in Table 17-2 below. 


Table 17-2, Sequential Access Method Operations by Function. 

Access 

Video 

CloseByteStream 

OpenByteStream 

QueryVidBs 


File 

Input 

GetBsLfa 

ReadBsRecord 

SetBsLfa 

ReadByte 

ReadBytes 

Other 

Output 

CheckpointBs 

WriteBsRecord 

PutBackByte 

ReleaseByteStream 

WriteByte 

SetlmageMode 


Access 


Input 


CloseByteStream closes the open byte stream. 

OpenByteStream opens a device/ file as a byte 

stream. 


ReadBsRecord 


ReadByte 


ReadBytes 


reads the specified count of 
bytes from the open input byte 
stream to the specified memory 
area . 

reads 1 byte from the open 
input byte stream. 

reads up to the specified count 
of bytes from the open input 
byte stream. 
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Output 


WriteBsRecord writes the specified count of 

bytes to the open output byte 
stream from the specified 
memory area . 

WriteByte writes 1 byte to the open 

output byte stream. 

Video 

QueryVidBs returns information about video 

byte streams to the client 
structure . 

File 

GetBsLf a returns the logical file 

address at which the next 
input/output operation will 
occur for the open byte stream. 

SetBsLfa sets the logical file address 

at which the input/output 
operation is to continue for 
the open file byte stream. 

Other 

CheckpointBs checkpoints the open output 

byte stream. 

PutBackByte returns 1 byte to the open 

input byte stream. 

ReleaseByteStream 

abnormally closes the 
device/file associated with the 
open output byte stream. 

SetlmageMode sets normal, image, or binary 

mode . 
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CheckpointBs 

Description 

The CheckpointBs procedure checkpoints the open 
output byte stream identified by the memory 
address of the Byte Stream Work Area. 
CheckpointBs writes any partially full buffers 
and waits for all write operations to complete 
successfully before returning. The byte stream 
remains open for subsequent output. 

Procedural Interface 

CheckpointBs (pBSWA) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

Request Block 

CheckpointBs is an object module procedure. 
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CloseByteStream 

Description 

The CloseByteStream procedure closes the open 
byte stream identified by the memory address of 
the Byte Stream Work Area. If the byte stream 
was open for output, then CloseByteStream writes 
any partially full buffers and waits for all 
write operations to complete before returning. 
After calling CloseByteStream, the process can 
reuse the Byte Stream Work Area and buffer 
area. If an error occurs during a 

CloseByteStream operation, then the byte stream 
is closed and a status code is returned. 

Procedural Interface 

CloseByteStream (pBSWA) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

Request Block 

CloseByteStream is an object module procedure. 
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GetBsLfa 


Description 

The GetBsLfa procedure returns the logical file 
address at which the next input/output operation 
will occur for the open byte stream identified by 
the memory address of the Byte Stream Work Area. 

GetBsLfa is only valid for file byte streams; 
otherwise it returns status code 7 ("Not 
implemented" ) . 

Procedural Interface 

GetBsLfa (pBSWA, pLfaRet) ; ErcType 
where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

pLfaRet is the memory address of 4 bytes to 

which the current logical file 
address is to be returned. 

Request Block 

GetBsLfa is an object module procedure. 
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OpenByteStream 

Description 

The OpenByteStream procedure opens a device/ file 
as a byte stream. If an output byte stream is 
opened for a file that does not already exist, 
OpenByteStream creates it. The address of the 
Byte Stream Work Area supplied to OpenByteStream 
must be supplied to subsequent operations such as 
ReadBytes, WriteBsRecord , and CloseByteStream to 
identify this particular byte stream. 

Procedural Interface 

OpenByteStream (pBSWA, pbFileSpec, cbFileSpec, 

pbPas sword, cbPas sword, mode, 

pBufferArea, 

sBuf ferArea) : ErcType 

where 

pBSWA is the memory address of a 130-byte 

memory work area for use by SAM 
procedures . 

pbFileSpec 

cbFileSpec describe a device or file specifica- 
tion. See the "Device/File 

Specifications" section above. 

pbPas sword 

cbPassword describe a device, volume, 

directory, or file password. The 
Kbd, Vid, Comm, and Nul devices do 
not require passwords. 

mode is read, text, write, append, or 

modify. This is indicated by 16-bit 
values representing the ASCII 
constants "mr" , "mt" , "mw" , "ma" , or 
"mm". In these ASCII constants, the 
first character (m) is the high- 
order byte and the second character 
(r, t, w, a, or m, respectively) is 
the low-order byte. This is the 
reverse of the byte order of strings 
in Convergent programming languages. 

Mode jread reads an existing file 
Trom the beginning. 

Mode text reads an existing file 
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from the beginning. Mode text is 
identical to mode read except when 
used to read Word Processor files. 
The text of a Word Processor file is 
followed by formatting information, 
which is not usually desired. When 
mode text is specified, status code 
1 ("End of file") is returned after 
the last byte of text is read (that 
is, the formatting information is 
ignored) . 

Mode write overwrites a previously 
existing file of the specified name 
(if any) and adjusts the length as 
necessary. If a file of the 
specified name does not exist, SAM 
creates one. 

Mode append appends output to the 
end of an existing file (if any). 
If a file of the specified name does 
not exist, SAM creates one. 

Mode modify is only applicable to 
communications byte streams and 
indicates that both reading and 
writing are allowed on the same 
communications channel . 


pBuf ferArea 

sBufferArea describe a memory area provided for 
the exclusive use of SAM 
procedures. To ensure device 

independence, this area must be at 
least 1024 bytes and word-aligned. 
Providing a larger area improves the 
efficiency of file operations. 


Request Block 


OpenByteStream is an object module procedure. 
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PutBackByte 

Description 

The PutBackByte procedure returns 1 byte to the 
open input byte stream identified by the memory 
address of the Byte Stream Work Area. This can 
be useful to a program such as a compiler that 
may decide, after looking at a character, that it 
should be processed by a different routine. Only 
1 byte can be put back before reading again. An 
attempt to put back more than 1 byte returns 
status code 2305 ("Too many put backs"). 

Procedural Interface 

PutBackByte (pBSWA, b) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

b is the 8-bit byte to be put back. 

Request Block 

PutBackByte is an object module procedure. 
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QueryVidBs 

Description 


The QueryVidBs procedure returns information 
about video byte streams to the client structure. 

Procedural Interface 

QueryVidBs (pBSWA, pBsVidStateRet) : ErcType 
where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

pBsVidStateRet 

is the memory address of a 16-byte 
structure of the format: 

Size 

Byte Field (bytes) 

0 number of frame 1 

1 number of lines in frame 1 

2 number of columns in 1 

frame 

3 current line number 1 

4 current column number 1 

5 cursor visible 1 

(TRUE/FALSE) 

6 pausing between full 1 

frames of text enabled 
(TRUE/FALSE) 

7 current character attri- 1 

bute mode, as specified 

in controlling character 
attributes escape sequence 

8 literal mode (TRUE/FALSE) 1 

9 reserved 7 


Request Block 


QueryVidBs is an object module procedure. 
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ReadBs Record 


Description 

The ReadBsRecord procedure reads the specified 
count of bytes from the open input byte stream 
identified by the memory address of the Byte 
Stream Work Area to the specified memory area. 
ReadBsRecord always reads the count of bytes 
specified except when fewer than that count 
remain in the file or when an input/ output error 
occurs. If fewer than the specified count of 
bytes (or no bytes) remain in the file, status 
code 1 ("End of file") is returned in conjunction 
with the actual count of bytes read. 

Procedural Interface 

ReadBsRecord (pBSWA, pBufferRet, sBufferMax, 
psDataRet ) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByte Stream. 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. 

sBufferMax is the count of bytes to be read to 
memory. 

psDataRet is the memory address of the word to 
which the count of bytes 
successfully read is returned. 

Request Block 

ReadBsRecord is an object module procedure. 


17-28 CTOS™ Operating System Manual 



ReadByte 

Description 


The ReadByte procedure reads 1 byte from the open 
input byte stream identified by the memory 
address of the Byte Stream Work Area. If no 
bytes remain in the file, status code 1 ("End of 
file") is returned. 

Procedural Interface 

ReadByte (pBSWA, pbRet) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

pbRet is the memory address of the byte to 

which the data is returned. 

Request Block 

ReadByte is an object module procedure. 
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ReadBytes 

Description 


The ReadBytes procedure reads up to the specified 
count of bytes from the open input byte stream 
identified by the memory address of the Byte 
Stream Work Area. The count of bytes made 
available by this operation is chosen to optimize 
hardware performance and is not predictable. It 
can range from 1 to the specified maximum. 

ReadBytes returns the memory address of the data 
bytes in its buffer rather than moving the data 
to a specified location. This optimizes 
performance, but imposes the restriction that the 
calling process completely process the data 
before calling ReadBytes again. If this 
restriction is inconvenient, the ReadBsRecord 
operation should be used instead. If no bytes 
remain in the file, status code 1 ("End of file") 
is returned. 


Procedural Interface 

ReadBytes (pBSWA, cbMax, ppbRet, pcbRet) : ErcType 


where 

pBSWA 

cbMax 

ppbRet 

pcbRet 


is the memory address of the same 
Byte Stream Work Area that was 
supplied to OpenByteStream. 

is the maximum count of bytes of 
data that the calling process will 
accept . 

is the memory address of 4 bytes to 
which the memory address of the data 
is returned. 

is the memory address of a word to 
which the actual count of data bytes 
made available is returned. 


Request Block 


ReadBytes is an object module procedure. 
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ReleaseByteStream 

Description 

The ReleaseByteStream procedure abnormally closes 
the device/file associated with the open output 
byte stream identified by the memory address of 
the Byte Stream Work Area. ReleaseByteStream, 
unlike the CloseByteStream operation, does not 
properly write remaining partially fuTT 
buffers. ReleaseByteStream should only be used 
when a WriteBsRecord, WriteBytes, or CheckpointBs 
operation fails due to a device error. 

Procedural Interface 

ReleaseByteStream (pBSWA) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

Request Block 

ReleaseByteStream is an object module procedure. 
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SetBsLfa 


Description 

The SetBsLfa procedure sets the logical file 
address at which the input/output operation is to 
continue for the open file byte stream identified 
by the memory address of the Byte Stream Work 
Area. If each of the 4 bytes of the lfa contain 
OFFh, then the lfa of the file byte stream is set 
to the end-of-file lfa of the file. After 
setting the lfa to the end-of-file, the GetBsLfa 
operation can be called to determine the length 
of the file. 

SetBsLfa is only valid for file byte streams; 
otherwise it returns status code 7 ("Not 
implemented" ) . 

Procedural Interface 

SetBsLfa (pBSWA, lfa): ErcType 


is the memory address of the same 
Byte Stream Work Area that was 
supplied to OpenByteStream. 

is the byte offset, from the 
beginning of the file, of the next 
byte to be read/written. 


where 

pBSWA 

lfa 

Request Block 


SetBsLfa is an object module procedure. 
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SetlmageMode 

Description 


The SetlmageMode procedure sets the normal, 
image, or binary mode for printer, spooler, and 
communications byte streams. SetlmageMode, if 
attempted on other byte streams, returns status 
code 7 ("Not implemented"). 

Procedural Interface 

SetlmageMode (pBSWA, mode) : ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

mode is a code as follows: 

0 for normal mode 

1 for image mode 

2 for binary mode 

Request Block 

SetlmageMode is an object module procedure. 
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WriteBs Record 


Description 

The WriteBsRecord procedure writes the specified 
count of bytes to the open output byte stream 
identified by the memory address of the Byte 
Stream Work Area from the specified memory 
area. Because output is buffered, there is no 
guarantee of the time at which output is actually 
written. Only the CheckpointBs and 

CloseByteStream operations ensure that data was 
actually written. 

Procedural Interface 

WriteBsRecord (pBSWA, pb, cb, pcbRet) : ErcType 
where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream . 

pb is the memory address of the data to 

be written. 

cb is the count of bytes to write. 

pcbRet is the memory address of the word to 

which the count of data bytes 
successfully written is returned. 

Request Block 

WriteBsRecord is an object module procedure. 
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WriteByte 

Description 


The WriteByte procedure writes 1 byte to the open 
output byte stream identified by the memory 
address of the Byte Stream Work Area. Because 
output is buffered, there is no guarantee of the 
time at which output is actually written. Only 
the CheckpointBs and CloseByteStream operations 
ensure that data was actually written. 

Procedural Interface 

WriteByte (pBSWA, b): ErcType 

where 

pBSWA is the memory address of the same 

Byte Stream Work Area that was 
supplied to OpenByteStream. 

b is the 8-bit byte to write. 

Request Block 

WriteByte is an object module procedure. 
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18 RECORD SEQUENTIAL ACCESS METHOD 


OVERVIEW 


The Record Sequentia l Access Method (RSAM) 
provides efficient sequential access to fixed- 
and variable-length records . Records are read 
and written using sequential, overlapped input 
and output. Records are both blocked (that is, 
as many records as possible are packed in each 
physical sector) and spanned (that is, logical 
records are permitted to cross physical sector 
boundaries) . There is also an operation to scan 
forward to the next well- formed record following 
detection of a malformed record. Files can be 
opened for read, write (which replaces any prior 
file content), and append. 

RSAM can be called directly from any of the 
Convergent programming languages. RSAM is a 
library of object module procedures. 


Record Sequential Access Method 


18-1 



CONCEPTS 


RSAM Files and Records 

The Record Sequential Access Me thod (RSAM) 
provides efficient sequential access to fixed- 
and variable-length records in a file. An RSAM 
file is a sequence of these records. 

A record can be as large as 65,527 bytes or as 
small as 1 byte. Records are packed into disk 
sectors to provide efficient disk storage use. 
RSAM packs records on write and unpacks them on 
read. The structure of RSAM records, record 
headers, record trailers, and the initial sectors 
of an RSAM file are explained in the "File Access 
Methods" section. 

If a sector cannot be read or a record is 
malformed, the remainder of the file can be read 
after the ScanToGoodRsRecord operation is used to 
locate the next well-formed record. 


Working Area 


RSAM uses a work area supplied by the application 
system. A Record Sequential Work Area (RSWA) is 
a 150-byte memory work area for the exclusive use 
of the RSAM procedures. Any number of RSAM files 
can be open simultaneously using separate RSWAs . 


Buffer 


RSAM also uses a word-aligned buffer supplied by 
the application system. The buffer must be at 
least 1,024 bytes long. The buffer size is not 
constrained by the longest record to be read or 
written, but performance is improved with the use 
of large buffers. 

RSAM uses overlapped output. Therefore, data 
written to an RSAM file can be retained in the 
buffer and not actually written to the file until 
some time after the WriteRsRecord operation 
returns. The CheckpointRsFile operation flushes 
the buffers of an RSAM file, ensuring that all 
data was written to disk. 
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OPERATIONS : PROCEDURES 


The Record Sequential Access Method provides the 

operations listed below. 

CheckpointRsFile checkpoints the open output 

RSAM file. 

CloseRsFile closes an RSAM file (including 

conclusion of all input/output 
operations ) . 

GetRsLfa returns the logical file 

address at which the next 
input/output operation will 
occur . 

OpenRsFile opens or creates an RSAM file. 

ReadRs Record reads the next record from an 

RSAM file. 

ReleaseRsFile releases all resources 

associated with an open RSAM 
file (for example, open files 
and exchanges). 

ScanToGoodRs Record 

scans forward to the next well- 
formed record in an RSAM file. 

WriteRsRecord writes a record to an RSAM 

file . 
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CheckpointRsFile 

Description 

The CheckpointRsFile procedure checkpoints the 
open output RSAM file identified by the memory 
address of the Record Sequential Work Area. 
CheckpointRsFile writes any partially full 
buffers and waits for all write operations to 
complete before returning. The RSAM file remains 
open for subsequent output. 

Procedural Interface 

CheckpointRsFile (pRSWA) : ErcType 

where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

Request Block 

CheckpointRsFile is an object module procedure. 
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CloseRsFile 


Description 

The CloseRsFile procedure closes the open RSAM 
file identified by the memory address of the 
Record Sequential Work Area. If the RSAM file 
was open for output, CloseRsFile writes any 
partially full buffers and waits for all write 
operations to complete before returning. After 
calling CloseRsFile, the Record Sequential Work 
Area and buffer area can be reused. If an error 
occurs during a CloseRsFile operation, the RSAM 
file is closed and the pertinent status code is 
returned . 

Procedural Interface 

CloseRsFile (pRSWA) : ErcType 
where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

Request Block 

CloseRsFile is an object module procedure. 
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GetRsLfa 


Description 


The GetRsLfa procedure returns the logical file 
address at which the next input/output operation 
will occur for the open RSAM file identified by 
the memory address of the Record Sequential Work 
Area . 

Procedural Interface 

GetRsLfa (pRSWA, pLfaRet) : ErcType 
where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

pLfaRet is the memory address of 4 bytes to 

which the current logical file 
address is to be returned. 

Request Block 

GetRsLfa is an object module procedure. 
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OpenRsFile 

Description 

The OpenRsFile procedure opens an RSAM file in 
read, write, or append mode. For write and 
append modes, if the file does not exist, it is 
created. The address of the Record Sequential 
Work Area supplied to OpenRsFile must be supplied 
to subsequent RSAM operations. 

Procedural Interface 

OpenRsFile (pRSWARet, pbFilespec, cbFilespec, 
pb Pas sword, cbPas sword, mode, 
pBufferArea, sBufferArea) : ErcType 

pRSWARet is the memory address of a 150-byte 

memory work area for use by the 
Record Sequential Access Method 
procedures . 

pbFilespec 

cbFilespec describe a character string 

specifying the name of the file to 
be opened . 

pb Pas sword 

cbPassword describe a character string 

specifying a password authorizing 
the requested file access. 

mode is read, write, or append. This is 

indicated by 16-bit values 
representing the ASCII constants 
"mr" (mode read), "raw" (mode write), 
or "ma" (mode append). In these 
ASCII constants, the first character 
(m) is the high-order byte and the 
second character (r, w, or a, 

respectively) is the low-order 
byte. This is the reverse of the 
byte order of strings in Convergent 
programming languages . 

Mode read reads an existing file 
from the beginning. 

Mode write overwrites a previously 
existing file of the specified name 
(if any) and adjusts the length as 
necessary. If a file of that name 
does not exist, RSAM creates one. 
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Mode append appends the records 
written to the end of an existing 
file ( if any) . If a file of the 
specified name does not exist, RSAM 
creates one. 

pBuf ferArea 

sBufferArea describe a memory area provided for 
the exclusive use of the RSAM 
procedures. This area must be at 
least 1,024 bytes long and word- 
aligned. Providing a larger area 
improves the efficiency of RSAM 
operations . 

Request Block 

OpenRsFile is an object module procedure. 
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ReadRs Record 


Description 

The ReadRsRecord procedure reads the next record 

from the open RSAM file identified by the memory 

address of the Record Sequential Work Area. 

Procedural Interface 

ReadRsRecord (pRSWA, pRecordRet, sRecordMax, 
pcbRet ) : ErcType 

where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

pRecordRet 

sRecordMax describe the memory area to which 

the record is to be read. 

pcbRet is the memory address of the word to 

which the number of bytes read is 
returned. If the record fits in the 
supplied memory area, pcbRet is the 
length of the record. If the record 
does not fit in the supplied memory 
area, pcbRet is sRecordMax and 

status code 3606 ("Record too 

large") is returned. 

Request Block 

ReadRsRecord is an object module procedure. 


Record Sequential Access Method 


18-9 



ReleaseRsFile 


Description 

The ReleaseRsFile procedure abnormally closes the 
file associated with the open output RSAM file 
identified by the memory address of the Record 
Sequential Work Area. ReleaseRsFile, unlike the 
CloseRsFile operation, does not properly write 
remaining partially full buffers. ReleaseRsFile 
should only be used when a WriteRsRecord or 
CheckpointRsFile operation fails because of a 
device error . 

Procedural Interface 

ReleaseRsFile (pRSWA) : ErcType 

where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

Request Block 

ReleaseRsFile is an object module procedure. 
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ScanToGoodRs Record 


Description 

The ScanToGoodRsRecord procedure is called after 
an attempt is made to read a malformed record or 
after a disk error occurs while reading the open 
RSAM file identified by the memory address of the 
Record Sequential Work Area. ScanToGoodRsRecord 
searches the sectors of the RSAM file until a 
valid record header is found. The double-check 
byte of the record found and the header of the 
following record are then checked, and if they 
are valid, the RSAM file is positioned to the 
record found. If the RSAM file is also a Direct 
Access Method (DAM) file, that is, a file of 
fixed-length records, record headers are only 
searched for at the positions where they can 
occur. These positions are computed by simple 
arithmetic involving the record length. 

ScanToGoodRsRecord reads every sector in the area 
scanned, so that sectors of the file that were 
damaged are detected and skipped. 

Procedural Interface 

ScanToGoodRsRecord (pRSWA, qbSkipMax, 

pLf aScanStartRet , 
pqbRet): ErcType 


where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

qbSkipMax is a 32-bit unsigned integer (the 

maximum number of bytes to skip 
while scanning) . 

pLf aScanStartRet 

is the memory address of a logical 
file address to which the byte 
offset in the RSAM file of the first 
byte skipped is returned. 

pqbRet is the memory address of a 32-bit 

unsigned integer to which the number 
of bytes skipped is returned. 
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Request Block 


ScanToGoodRsRecord is an object module procedure. 
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WriteRs Record 


Description 

The WriteRsRecord procedure writes a record to 
the open RSAM file identified by the memory 
address of the Record Sequential Work Area. The 
RSAM file is automatically extended to 

accommodate new records. Because output is 
buffered, there is no guarantee of the time at 
which output is actually written. Only the 
Che ckpointRs File and CloseRsFile operations 

ensure that data was actually written. 

Procedural Interface 

WriteRsRecord (pRSWA, pRecord, sRecord) : ErcType 
where 

pRSWA is the memory address of the same 

Record Sequential Work Area that was 
supplied to OpenRsFile. 

pRecord 

sRecord describe the memory area containing 

the record to be written. 

Request Block 

WriteRsRecord is an object module procedure. 
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19 DIRECT ACCESS METHOD 


OVERVIEW 


The Direct Access Method (DAM) provides efficient 
random access to fixed-length records. A record 
is referred to in DAM by the record number within 
a file. 

DAM can be accessed in the COBOL language through 
COBOL Relative 1-0. DAM can also be called 
directly from any of the Convergent programming 
languages. DAM is a library of object module 
procedures . 

In reading, writing, or deleting, DAM does simple 
address calculations based on the record number 
to find the required sectors of the DAM file. 
DAM keeps a cache of recently referenced sectors 
that are obtained without reference to the 
disk. Sectors not in the cache are accessed with 
a single disk access. 
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CONCEPTS 


DAM Files, Records, and Record Fragments 

The Direct Access Method (DAM) provides efficient 
random access to records identified by the record 
number within a file. A record number specifies 
the record position relative to the first record 
in a file. The record number of the first record 
in a file is 1 . 

A DAM file is a sequence of fixed-length 
records. The length of a record is specific to 
each DAM file and is specified when the file is 
first created. 

A record can be as large as 63,992 bytes or as 
small as 0 bytes. Records are packed into disk 
sectors to provide efficient disk storage use. 
DAM packs records on write and unpacks them on 
read. A packed record contains eight bytes of 
header and trailer in addition to the stored 
data . 

A record fragment is a contiguous area of memory 
within a record. A record fragment is specified 
using an offset from the beginning of the record 
and a byte count. The record fragment must be 
contained within the record. 


Working Area 


DAM uses a work area supplied by the application 
system. A Direct Access Work Area (DAWA) is a 
64-byte memory work area for the exclusive use of 
the DAM procedures. Any number of DAM files can 
be open simultaneously using separate DAWAs . 


Buffer 


DAM also uses a word-aligned buffer supplied by 
the application system. The buffer size is 
specified by the application system, subject only 
to the constraint that it be a multiple of 512 
greater than or equal to the record size plus 
519. This constraint can be relaxed in two 
cases. First, if 512 is a multiple of the record 
size plus eight, the minimal size is simply 
512. Second, if the record size plus eight is a 
multiple of 512, the minimal size is the record 
size plus eight. 
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Buffer Size and Sequential Access 


DAM reads and writes the buffer by using a single 
request to the file management system. This 
typically requires only a single disk access. 
Whenever the disk is read, the entire buffer is 
filled. If the buffer size is chosen to be 
larger than the record size (by at least a factor 
of two), the buffer acts as a look-ahead cache: 
if sequentially numbered records are requested, 
DAM typically finds them in the buffer and does 
not access the disk. In this way, if the 
application system makes a suitable choice of 
buffer size, the Direct Access Method can provide 
efficient record sequential access. 


Buffer Management Modes: Write-Through and Write-Behind 

DAM provides two modes of buffer management: 
write-through and write-behind . The mode is 
initially set to write-through when a DAM file is 
opened. The mode can be changed using the 
SetDaBuf ferMode operation. 

In the write- through mode , DAM immediately writes 
the changed sectors of the buffer to disk 
whenever a record is written or deleted. DAM 
guarantees that the file content on disk is 
accurate at the completion of a modify operation. 

In the write-behind mode , DAM writes changed 
sectors of the buffer to disk only when new 
sectors are brought into the buffer, the DAM file 
is closed, or the mode is changed to write- 
through. Write-behind mode provides better 
performance when DAM is used to modify records in 
sequential order. 
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OPERATIONS : PROCEDURES 


Direct Access Method operations are categorized 
by function in Table 19-1 below. 


Table 19-1. Direct Access Method Operations by Function. 

Access 

Input 

CloseDaFile 

ReadDaFragment 

OpenDaFile 

ReadDaRecord 

Inquiry 

Output 

QueryDaLastRecord 
Query Da RecordStatus 

DeleteDaRecord 

WriteDaFragment 

WriteDaRecord 

Other 


SetDaBuf f erMode 
Tr uncat eDaFile 



Access 

CloseDaFile closes a DAM file. 

OpenDaFile opens or creates a DAM file. 

Input 

ReadDaFragment reads a record fragment from an 

open DAM file. 

ReadDaRecord reads a record from a DAM file. 

Output 

DeleteDaRecord deletes a record from a DAM 

file. 

WriteDaFragment writes a record fragment to an 

open DAM file. 

WriteDaRecord writes a record to a DAM file. 
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Inquiry 


Query DaLastRecord 

copies to the specified area 
the number of the last record 
in an open DAM file. 

Query DaRecordStatus 

copies to the specified area 
the status of a record in an 
open DAM file. 


Other 


SetDaBuf ferMode sets the buffer management mode 

to write-through or write- 
behind . 

TruncateDaFile truncates an open DAM file 

(that is, it removes all 
records beyond a specified 
point) . 


Direct Access Method 


19-5 



CloseDaFile 


Description 


The CloseDaFile procedure closes the open DAM 
file identified by the memory address of the 
Direct Access Work Area. After calling 

CloseDaFile, the application system can reuse the 
Direct Access Work Area and the buffer area. 

Procedural Interface 

CloseDaFile (pDAWA) : ErcType 

where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

Request Block 

CloseDaFile is an object module procedure. 
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DeleteDaRecord 


Description 

The DeleteDaRecord procedure deletes a record 
from the open DAM file identified by the memory 
address of the Direct Access Work Area. The 

deleted record is specified by the record 

number. Once a record is deleted, it can no 
longer be read. 

Procedural Interface 

DeleteDaRecord (pDAWA, qiRecord) : ErcType 
where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
to be deleted. 

Request Block 

DeleteDaRecord is an object module procedure. 
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OpenDaFile 

Description 

The OpenDaFile procedure opens a DAM file in 
either read (shared) or modify (exclusive) 
mode. If the file does not exist, it is 
created. The address of the Direct Access Work 
Area supplied to OpenDaFile must be supplied to 
subsequent DAM operations. 

Access to a DAM file is most efficient if its 
sectors are physically contiguous. This 

contiguity can be increased by preallocating the 
file. To preallocate the file, follow the call 
to OpenDaFile that creates the file with a call 
to WriteDaRecord. This call to WriteDaRecord 
should specify a value of qiRecord large enough 
to preallocate the desired file length. This 
"end record" can then be deleted. 

Procedural Interface 

OpenDaFile (pDAWARet, pbFilespec, cbFilespec, 
pb Pas sword, cbPas sword, mode, 
pBuffer, sBuffer, sRecord) : ErcType 

where 

pDAWARet is the memory address of a 64-byte 

memory work area for use by the 
Direct Access Method procedures. 

pbFilespec 

cbFilespec describe a character string 

specifying the name of the file to 
be opened . 

pbPas sword 

cbPassword describe a character string 

specifying a password that 
authorizes the requested file 
access . 

mode is read (shared) or modify 

(exclusive). This is indicated by 
16-bit values representing the ASCII 
constants "mr" (mode read) or "mm" 
(mode modify) . In these ASCII 

constants, the first character (m) 
is the high-order byte and the 
second character (r or m, 
respectively) is the low-order 
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byte. This is the reverse of the 
byte order of strings in Convergent 
programming languages. 

pBuf fer 

sBuffer describe a word-aligned memory area 

provided for the exclusive use of 
the Direct Access Method 

procedures. The size of this area 
is discussed in the "Buffer" section 
above . 

sRecord describes the fixed record size for 

the DAM file. If the DAM file 
already exists, sRecord must match 
the record size specified when the 
file was created. 

Request Block 

OpenDaFile is an object module procedure. 
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Qu e r y DaLa s t Re c o r d 
Description 

The QueryDaLastRecord procedure copies to the 
specified area the number of the last record in 
the open DAM file. The file is identified by the 
memory address of the Direct Access Work Area. 
The last record is the existing record having the 
largest record number. 

If the DAM file contains no records, the last 
record number is 0. 

Procedural Interface 

QueryDaLastRecord (pDAWA, pqiRecordRet) : ErcType 
where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

pqiRecordRet is the memory address of the 32-bit 
memory area to which the last record 
number is written. 


Request Block 


QueryDaLastRecord is an object module procedure. 


19-10 


CTOS™ Operating System Manual 



QueryDaRecordStatus 

Description 


The QueryDaRecordStatus procedure copies to the 
specified area the status of a record in the open 
DAM file. The file is identified by the memory 

address of the Direct Access Work Area. The 

record status is interpreted in this way: 

ercOK the record exists. 

ercRecordDoesNotExist (code 3302) 

the record does not exist. 

ercRecordBeyondExistingRecords (code 3007) 

the record does not exist. The 
record has a larger record number 
than any existing record. 

Caution: The status code value returned by 

QueryDaRecordStatus is the status of the 
operation, not the record status. The memory 

address of the record status is passed as a 
parameter . 

Procedural Interface 

QueryDaRecordStatus (pDAWA, qiRecord, 

pStatusRet): ErcType 


where 


pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
to query. 


pStatusRet is the memory address of a word to 
which the record status is written. 


Request Block 


QueryDaRecordStatus is an object module 
procedure. 
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ReadDaFragment 

Description 


The ReadDaFragment procedure reads a record 

fragment from the open DAM file identified by the 

memory address of the Direct Access Work Area. 

The returned record fragment is specified by the 

record number, relative offset, and byte count. 

Procedural Interface 

ReadDaFragment (pDAWA, qiRecord, pFragmentRet , 

rbFragment, cbFragment): ErcType 

where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
containing the record fragment to be 
read. qiRecord must correspond to 
an existing record . 

pFragmentRet 

is the memory address of the memory 
area to which the record fragment is 
returned . 

rbFragment is the offset from the beginning of 
the record to the first byte of the 
record fragment. 

cbFragment is the size of the record fragment. 

Request Block 

ReadDaFragment is an object module procedure. 
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ReadDaRecord 


Description 

The ReadDaRecord procedure reads a record from 
the open DAM file identified by the memory 
address of the Direct Access Work Area. The 
returned record is specified by the record 
number . 

Procedural Interface 

ReadDaRecord (pDAWA, qi Record, 

pRecordRet): ErcType 

where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
to be read. qiRecord must 

correspond to an existing record. 

pRecordRet is the memory address of the memory 
area to which the record is 
returned . 

Request Block 

ReadDaRecord is an object module procedure. 
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SetDaBuf ferMode 


Description 


The SetDaBuf ferMode procedure sets the buffer 
management mode to write-through or write- 
behind . These two buffering modes are described 
in the "Concepts" section above. 

Procedural Interface 

SetDaBuf ferMode (pDAWA, mode): ErcType 
where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

mode is either the write- through or 

write-behind buffer management 
mode. This is indicated by 16-bit 
values representing the ASCII 
constants "wt" (write- through) and 
"wb" (write-behind). In these ASCII 
constants, the first character (w) 
is the high-order byte and the 
second character (t or b, 
respectively) is the low-order 
byte. This is the reverse of the 
byte order of strings in Convergent 
programming languages . 

Request Block 

SetDaBuf ferMode is an object module procedure. 


19-14 


CTOS" Operating System Manual 



TruncateDaFile 


Description 

The TruncateDaFile procedure truncates the open 
DAM file (that is, it removes all records beyond 
a specified point) . All records having record 
numbers greater than the qiRecord parameter are 
deleted. If qiRecord is 0, all records in the 
DAM file are deleted. 

Procedural Interface 

TruncateDaFile (pDAWA, qiRecord): ErcType 
where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying a record number. All 
records having record numbers 
greater than qiRecord are deleted. 

Request Block 

TruncateDaFile is an object module procedure. 
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WriteDaFragment 

Description 

The WriteDaFragment procedure writes a record 
fragment to the open DAM file identified by the 
memory address of the Direct Access Work Area. 
The written record fragment is specified by the 
record number, relative offset, and byte count. 
The DAM file is automatically extended to 
accommodate new records. 

Procedural Interface 

WriteDaFragment (pDAWA, qi Record, pFragment, 

rbFragment, cbFragment): ErcType 

where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
containing the record fragment to be 
written . 

pFragment is the memory address of the memory 
area from which the record fragment 
is written. 

rbFragment is the offset from the beginning of 
the record to the first byte of the 
record fragment . 

cbFragment is the size of the record fragment. 

Request Block 

WriteDaFragment is an object module procedure. 
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WriteDaRecord 


Description 

The WriteDaRecord procedure writes a record to 
the open DAM file identified by the memory 
address of the Direct Access Work Area. The 
written record is specified by the record 
number. The DAM file is automatically extended 
to accommodate new records . 

WriteDaRecord can write a record with a record 
number larger than any existing record number. 
If this is done, the file is extended and 
standard record header and trailer formats are 
written automatically to all added sectors. The 
time required for the WriteDaRecord operation is 
proportional to the amount by which the file is 
extended. 

Procedural Interface 

WriteDaRecord (pDAWA, qiRecord, pRecord): ErcType 
where 

pDAWA is the memory address of the same 

Direct Access Work Area that was 
supplied to OpenDaFile. 

qiRecord is a 32-bit unsigned integer 

specifying the number of the record 
to be written. 

pRecord is the memory address of the memory 

area from which the record is 
written . 

Request Block 

WriteDaRecord is an object module procedure. 
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20 INDEXED SEQUENTIAL ACCESS METHOD 


OVERVIEW 

Th e Indexed Sequ ential Access Method (ISAM) 
provides efficient, yet flexible, random access 
to fixed-length records identified by multiple 
keys stored in disk files. 

Each ISAM data set holds one type of data 
record. The size of the data records, the number 
of keys, and the type of each key are specified 
when an ISAM data set is created. 

ISAM, a software product, is described in the 
ISAM Manual. 
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CONCEPTS 


Key Types 

A record can have an unlimited number of keys. 
Each key is described by its position in the 
record~^Tof f set from the first byte of the 
record), the key length, and the key type. 

There are six key types : 

o byte string (up to 64 bytes), 

o character string (up to 64 bytes), 

o packed decimal (COBOL COMP-3), 

o binary, 

o long real, and 

o short real. 

Key type is important because the collating 
sequence depends on it. 

Each key defines an index (that is, an inversion) 
which is automatically updated when records are 
stored or modified and which is used as the basis 
of retrieval. Records can be retrieved in key- 
order sequence by any key field, starting with 
any key value. 

To increase flexibility, the following parameters 
can be specified for each key at the time an ISAM 
data set is created: 

o whether duplicates are allowed, 

o whether the index is to be kept in ascending 
or descending order, and 

o whether indexing of a record whose key field 
contains a null value is to be suppressed. 
(Suppressing the indexing of such fields 
reduces the size of the index.) 


File Types 


Each ISAM data set holds one record type but is 
stored as two physical files: a data store file 
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and an index file. These can be placed on 
different physical volumes if desired. 

The data store file holds the data records. 
Because all the records in a data set have the 
same length, physical space management that 

conserves disk space is simple and efficient: 
whenever a record is deleted, its space is added 
to a free list and later reused when a new record 
is created. 

The data store file is a Direct Access Method 
(DAM) file. See the "Direct Access Method" 

section . 

The index file holds all indexes for all of a 
data set's keys. Each index is implemented as a 
B-tree. This implementation technique, sometimes 
called "block splitting," ensures that data 
records can be repeatedly added without creating 
long overflow chains or requiring physical 
reorganization. 


Operations 

ISAM supports four principal kinds of 
operations: storing, reading, modifying, and 

deleting. 

When an application system stores a new record, 
ISAM automatically indexes the record according 
to the values in all its key fields. 

When an application system reads an existinq 
record, it can retrieve any of the following: 

o all records whose keys have a specific value 
(that is, an exact match ) , 

° all records whose key values lie in a 
specified range (that is, a range match ) , or 

o all records in which the initial bytes of a 
byte or character string key match a 
particular value (that is, a prefix match ). 

An application system can retrieve either the 
specified records in order, or a sequence of 
4-byte unique record identifiers in order. If 
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record identifiers are retrieved, then the appli- 
cation program can later obtain the corresponding 
data records by a special form of the retrieval 
operation, without reaccessing the index. 

Modifying an existing record combines storing and 
reading. Before a record is modified, it is 
automatically removed from each index for which 
the key field is being changed, then indexed 
under the new key field. 


ISAM Organization 

The ISAM facility consists of: 
o a multiuser access package, 

o a single-user access package, and 

o utilities. 

The multiuser access package and the single-user 
access package provide identical procedural 
interfaces to the application system. 


Multiuser Access Package 

The ISAM multiuser access package provides shared 
access to ISAM data sets from several cluster 
workstations. ISAM must be resident on the 
master (or standalone) workstation. ISAM 
operations are invoked using the standard CTOS 
request model, either by making an Operating 
System request or by invoking a procedure (which 
automatically makes the request). 


Single-User Access Package 

The ISAM single-user access package provides 
exclusive access to ISAM data sets from a single 
application partition of the workstation on which 
the application system runs. ISAM must be linked 
into the application system and then initialized 
by invoking an initialization procedure. ISAM 
operations are invoked by calling ISAM procedures 
directly. ISAM operations can be invoked by only 
one process at a time. 
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Utilities 


ISAM includes utilities that are invoked from the 
Executive. The ISAM Create utility creates an 
empty ISAM data set. The ISAM utilities ISAM 
Copy, ISAM Rename, ISAM Delete, and ISAM Set 
Protection provide capabilities for ISAM data 
sets similar to those the Executive commands 
Copy, Rename, Delete, and Set Protection provide 
for individual files. The ISAM Status utility 
displays information about an ISAM data set. The 
ISAM Reorganize utility changes the key fields of 
a data set, loads data from files, and recovers 
data from data sets that have become malformed. 
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21 DISK MANAGEMENT 


OVERVIEW 


Disk management operations provide device-level 
access to disk devices, in contrast to the file- 
level . access provided by file management 
operations. Access to a disk device at such a 
level is necessary in order to read a floppy disk 
written on a non-Convergent system or to format 
an uninitialized disk. 

Device-level access is provided to IBM- 
compatible, single-sided, 8-inch floppy disks 
written in either single or double density with 
sector sizes of 128, 256, 512, or 1024. The 
sector size and density of a floppy disk, if 
other than 512-byte double density, must be 
specified with the SetDevParams operation. 
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CONCEPTS 


Accessing a Disk Device 

A device can be accessed by using an OpenFile 
operation with a device or volume specifica- 
tion. The Read, Write, ReadAsync and CheckRead- 
Async, WriteAsync and CheckWriteAsync, and 
CloseFile operations all accept a file handle 
returned by such an OpenFile operation. (File 
handles are discussed in detail in the "File 
Management" section.) 

Device-level access to disks bypasses the 
concurrency control of the file management 
system. Thus extreme care is required if device- 
level access is used in a cluster configuration. 


Device Specification and Device Password 

A disk device is a physical hardware entity. 
Access to a device requires presentation of a 
device specification and a password. A device 
specification can take either of two forms, 
depending on whether the medium of the disk 
device contains a valid file system. 

If a volume contains a valid file system, the 
device specification has the form: 

{ node } [ volname] 

(In this case, the volume password of the volume 
must be specified. Volume passwords are 
described in the "File Management" section.) 

However, if the medium does not contain a valid 
file system (either because the medium was never 
initialized to contain one or because the file 
system has become malformed), the device 
specification has the form: 

{ node | [ devname] 

(In this case, the device password of the device 
must be specified. A device password protects a 
device. It can have a maximum of 12 characters, 
consisting of all alphanumeric characters plus 
the period, and the hyphen, "-".) 
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A volname (volume name) or a devname (device 
name] Is a string of characters. A volname or 
devname can have a maximum of 12 characters, 
consisting of all alphanumeric characters, plus 
the period, " . " , and the hyphen, 
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OPERATIONS : 


Access 


Input/output 


PROCEDURES AND SERVICES 

Disk management operations are categorized by 
function in Table 21-1 below. 


Table 21-1. 

Disk Management Operations by Function. 

Access 

Input/ Output 

CloseFile 

CheckReadAsync 

OpenFile 

CheckWriteAsync 


Format 

Other 

Read 


ReadAsync 

DismountVolume 

Write 

GetVHB 

WriteAsync 

MountVolume 


QueryDCB 


SetDevParams 



CloseFile closes an open file handle. 

OpenFile opens a device and returns a file 

handle . 


CheckReadAsync 

waits for input completion, checks 
the status code, and obtains the 
byte count of data read after a 
ReadAsync procedure. 

CheckWriteAsync 

waits for output completion, checks 
the status code, and obtains the 
byte count of data written after a 
WriteAsync procedure. 

Format initializes the surface of a floppy 

disk or other disk media to 
accommodate fixed-size data 
sectors. Used by the IVolume 
utility . 
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Read transfers an integral number of 

128- , 256-, 512- , or 1024-byte 
sectors from disk to memory. 

ReadAsync initiates the transfer of an 

integral number of 128-, 256-, 512-, 
or 1024-byte sectors from disk to 
memory. The CheckReadAsync 
procedure must be used to check the 
completion status of the transfer. 

Write transfers an integral number of 

128-, 256-, 512-, or 1024-byte 
sectors from memory to disk. 

WriteAsync initiates the transfer of an 

integral number of 128-, 256-, 512-, 
or 1024-byte sectors from memory to 
disk. The CheckWriteAsync procedure 
must be used to check the completion 
status of the transfer. 

Other 

DismountVolume 

dismounts the specified volume. 

GetVHB copies the Volume Home Block of the 

specified device to the specified 
memory area. 

MountVolume mounts the volume on the specified 
disk drive. 

QueryDCB copies the Device Control Block of 

the specified device to the 
specified memory area. 

SetDevParams 

allows the characteristics of the 
floppy disk controller to be 
modified to accommodate non- 
Convergent floppy disks. 
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CheckReadAsync 

Description 


After calling the ReadAsync procedure to initiate 
a read, the requesting process continues 

execution. When the process wants to synchronize 
with the asynchronous read (that is, wait for its 
completion), the process does a CheckReadAsync. 
The CheckReadAsync procedure waits for input 
completion, checks the status code, and obtains 
the byte count of data read. 

Status code 248 ("Wrong pRq argument") is 
returned if the pRq argument does not match the 
one of the preceding ReadAsync procedure. 

Procedural Interface 

CheckReadAsync (pRq, psDataRet) : ErcType 
where 

pRq is the same memory address as given 

in the pRq argument of the ReadAsync 
procedure . 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully read is to be returned. 

Request Block 


The ReadAsync and CheckReadAsync procedures are 
procedural interfaces to the Read operation. See 
the Read operation below. 
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CheckWr i te Async 
Description 


After calling the WriteAsync procedure to 
initiate a write, the requesting process 
continues execution. When the process wants to 
synchronize with the asynchronous write (that is, 
wait for its completion), the process does a 
CheckWriteAsync. The CheckWriteAsync procedure 
waits for output completion, checks the status 
code, and obtains the byte count of data written. 

Status code 248 (""Wrong pRq argument") is 
returned if the pRq argument does not match the 
one of the preceding WriteAsync procedure. 

Procedural Interface 

CheckWriteAsync (pRq, psDataRet) : ErcType 
where 

pRq is the same memory address as given 

in the pRq argument of the 
WriteAsync procedure. 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully written is to be returned. 


Request Block 


The WriteAsync and CheckWriteAsync procedures are 
procedural interfaces to the Write operation. 
See the Write operation below. 
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CloseFile 


Description 

The CloseFile service closes an open file. 

Procedural Interface 

CloseFile (fh): ErcType 
where 

fh is the file handle returned from an 

OpenFile operation. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNutn 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

10 

12 

fh 

2 
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Di smoun tVo 1 ume 


Description 

The DismountVolume service dismounts the 
specified volume. 

Dismounting (and mounting) of volumes is normally 
controlled by the Automatic Volume Recognition 
(AVR) capability of the file management system. 
The Dismount (and Mount) operations are provided 
for the use of utilities, such as IVolume, that 
must override AVR. (IVolume is described in the 
System Utilities Manual . ) 

Procedural Interface 

DismountVolume (pbVolName, cbVolName, pbPassword, 

cb Pas sword): ErcType 

where 

pbVolName 

cbVolName describe a character string of the 

form {node} [volname] . Square 

brackets are optional for the device 
name. The distinction between 

uppercase and lowercase is not 
significant in matching device 
names . 

pbPassword 

cbPassword describe the volume password that 

authorizes access to the specified 
volume . 
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Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

reserved 

6 

18 

pbVolName 

4 

22 

cbVolName 

2 

24 

pb Pas sword 

4 

28 

cbPas sword 

2 
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Format 


Description 

The Format service initializes the surface of a 
floppy disk or other disk media to accommodate 
fixed-size data sectors. Format is used by the 
IVolume utility (described in the System 
Utilities Manual ) and is device-dependent. See 
the Peripherals Hardware Manual for the control 
information required for a specific device. 

Procedural Interface 

Format (fh, pBuffer, sBuffer, lfa, 
psDataRet): ErcType 


where 

fh 


pBuffer 


sBuffer 


lfa 


is a file handle returned from an 
OpenFile operation that specifies a 
device . 

is the memory address of the first 
byte of control information. The 
buffer must be word aligned. 

is the count of bytes of control 
information to be transferred. It 
must be a multiple of 2 . 

is the byte offset, from the 
beginning of the device, of the 
first sector to be initialized. 


psDataRet is the memory address of the word to 
which the count of bytes success- 
fully transferred is to be returned. 
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Request Block 


ssDataRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

excbResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

38 

12 

fh 

2 


14 

lfa 

4 


18 

pBuf fer 

4 


22 

sBuf fer 

2 


24 

psDataRet 

4 


28 

ssDataRet 

2 

2 
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GetVHB 


Description 

The GetVHB service copies the Volume Home Block 
of the specified device to the specified memory 
area. if the specified area is not large enough 
to hold the requested information, the 
information is truncated. 

GetVHB does not require a password. To avoid 
security violations, 0's are returned in the 
volPassword field of the Volume Home Block. 

The Volume Home Block is described in the "File 
Management" section. 

Procedural Interface 

GetVHB (pbDevSpec, cbDevSpec, pVhbRet, 
sVhbMax): ErcType 

where 

pbDevSpec 

cbDevSpec describe a character string of the 
form {node} [devname] or {node}[vol- 
name] . Square brackets are optional 
for the device name. The 

distinction between uppercase and 
lowercase is not significant in 
matching device names . 

pVhbRet 

sVhbMax describe the memory area. 
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Request Block 


Offset 

Field 

Size 
(bytes ) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

15 

12 

reserved 

6 


18 

pbDevSpec 

4 


22 

cbDevSpec 

2 


24 

pVhbRet 

4 


28 

sVhbMax 

2 
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MountVolume 


Description 

The MountVolume service mounts the volume on the 
specified disk drive. 

Mounting (and dismounting) of volumes is normally 
controlled by the Automatic Volume Recognition 
(AVR) capability of the file management system. 
The Mount (and Dismount) operations are provided 
for the use of utilities, such as IVolume, that 
must override AVR. (IVolume is described in the 
System Utilities Manual . ) 

Procedural Interface 

MountVolume (pbDevSpec, cbDevSpec, pbDevPas sword, 
cbDevPas sword ) : ErcType 

where 

pbDevSpec 

cbDevSpec describe a character string of the 

form {node} [devname] . Square 

brackets are optional for the device 
name. The distinction between 

uppercase and lowercase is not 
significant in matching device 
names . 

pb Pas sword 

cbPassword describe the device password that 

authorizes access to the specified 
device . 
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Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

11 

12 

reserved 

6 


18 

pbDevSpec 

4 


22 

cbDevSpec 

2 


24 

pb Pas sword 

4 


28 

cbPassword 

2 



21-16 


CTOS’" Operating System Manual 



OpenFile 

Description 

The disk management form of the OpenFile service 
opens the entire specified volume/device as a 
file and returns a file handle. The file handle 
returned by OpenFile is used to refer to the file 
in subsequent operations such as Read, Write, and 
CloseFile . 

Procedural Interface 

OpenFile (pFhRet, pbDevSpec, cbDevSpec, 

pbPas sword, cbPas sword, mode): ErcType 

where 

pFhRet is the memory address of the word to 

which the file handle is returned. 

pbDevSpec 

cbDevSpec describe a character string of the 
form {node} [devname] or {node} [vol- 
name] . The distinction between 

uppercase and lowercase is not 
significant in matching device 
names . 

pbPas sword 

cbPas sword describe either the device or volume 
password that authorizes access to 
the specified device. 

mode is read or modify. This is 

indicated by 16 -bit values 
representing the ASCII constants 
"mr" (mode read) and "mm" (mode 
modify). in these ASCII constants, 
the first character (m) is the high- 
order byte and the second character 
(r or m, respectively) is the low- 
order byte. This is the reverse of 
the byte order of strings in 
Convergent programming languages. 

Access in read mode permits the 
returned file handle to be used as 
an argument only to the Read, 
ReadAsync, CheckReadAsync, and 
CloseFile operations. Access in 
modify mode, however, also permits 
the returned file handle to be used 
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as an argument to the WriteAsync, 
CheckWriteAsync, and Write opera- 
tions . 

There is no limit to the number of 
concurrent opens of a disk device in 
either read or modify mode. 


Request Block 


sFhMax is the size of a file handle and is always 

2 . 


Offset 

Field 

Size 

(bytes) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

4 

12 

reserved 

2 


14 

mode 

2 


16 

reserved 

2 


18 

pbDevSpec 

4 


22 

cbDevSpec 

2 


24 

pbPas sword 

4 


28 

cbPas sword 

2 


30 

pFhRet 

4 


34 

sFhMax 

2 

2 
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QueryDCB 

Description 

The QueryDCB service copies the Device Control 
Block of the specified device to the specified 
memory area. If the specified area is not large 
enough to hold the requested information, the 
information is truncated. 

QueryDCB does not require a password. To avoid 
security violations, 0's are returned in the 
devPassword field of the Device Control Block. 

The Device Control Block is described in the 
"File Management" section. 

Procedural Interface 

QueryDCB (pbDevSpec, cbDevSpec, pDcbRet, 
sDcbMax): ErcType 

where 

pbDevSpec 

cbDevSpec describe a character string of the 
form {node} [devname] or {node}[vol- 
name] . Square brackets are optional 
for _ the device name. The 

distinction between uppercase and 
lowercase is not significant in 
matching device names . 

pDcbRet 

sDcbMax describe the memory area. 
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Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

excbResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

124 

12 

reserved 

6 


18 

pb Dev Spec 

4 


22 

cbDevSpec 

2 


24 

pDcbRet 

4 


28 

sDcbMax 

2 
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Read 


Description 

The Read service transfers an integral number of 
128-, 256-, 512-, or 1024-byte sectors from disk 
to memory. Read returns only when the requested 
transfer is complete. The ReadAsync and 

CheckReadAsync procedures are used to overlap 
computation and input/output transfer. 

To accommodate programming languages in which 
Read is a reserved word, ReadFile is permitted as 
a synonym for the Read service. 

Procedural Interface 

Read (fh, pBufferRet, sBufferMax, lfa, 
psDataRet): ErcType 

where 

fh isafile handle returned from an 

OpenFile operation. The device can 
be open in either read or modify 
mode . 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. The buffer must be 
word aligned. 

sBufferMax is the count of bytes to be read to 
memory. It must be a multiple of 
the sector size (128, 256, 512, or 

1024) . 

lfa is the byte offset, from the 

beginning of the file, of the first 
byte to be read. It must be a 
multiple of the sector size (128, 
256, 512, or 1024) . 

psDataRet is the memory address of the word to 
which the count of bytes success- 
fully read is to be returned. 
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Request Block 


ssDataRet is always 2. 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNum 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

fh 

2 

14 

If a 

4 

18 

pBuf ferRet 

4 

22 

sBuf ferMax 

2 

24 

psDataRet 

4 

28 

ssDataRet 

2 
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ReadAsync 

Description 

The ReadAsync procedure initiates the transfer of 
an integral number of 128-, 256-, 512-, or 1024- 
byte sectors from disk to memory. The CheckRead- 
Async procedure must be called to check the 
completion status of the transfer. 

The information returned by Read with its 
psDataRet argument and ErcType status is obtained 
by CheckReadAsync . 

Procedural Interface 

ReadAsync (fh, pBufferRet, sBufferMax, lfa, pRq, 
exchangeReply ) : ErcType 

where 

fh is a file handle returned from an 

OpenFile operation. The device can 
be open in either read or modify 
mode . 

pBufferRet is the memory address of the first 
byte of the buffer to which the data 
is to be read. The buffer must be 
word aligned. 

sBufferMax is the count of bytes to be read to 
memory. It must be a multiple of 
the sector size (128, 256, 512, or 

1024) . 

lfa is the byte offset, from the 

beginning of the file, of the first 
byte to be read. It must be a 
multiple of the sector size (128, 
256, 512, or 1024) . 

pRq is the memory address of a 64-byte 

area to be used as workspace by 
ReadAsync . 

exchangeReply 

is an exchange provided by the 
client process for the exclusive use 
of ReadAsync and CheckReadAsync. 
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Request Block 


The ReadAsync and CheckReadAsync procedures 
procedural interfaces to the Read operation, 
the Read operation above. 


are 

See 
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SetDevParams 


Description 

The SetDevParams service allows the characteris- 
tics of the 8-inch floppy disk controller to be 
modified to accommodate non-Convergent floppy 

disks . 

Procedural Interface 

SetDevParams (pbDevSpec, cbDevSpec, pbPassword, 
cbPas sword, paramCode): ErcType 

where 

pbDevSpec 

cbDevSpec describe a character string of the 
form node [devname] . Square 

brackets are optional for the device 

name. The distinction between 

uppercase and lowercase is not 
significant in matching device 
names . 

pbPassword 

cbPassword describe the device password that 

authorizes access to the specified 
device . 



paramCode 

describes 
tics to 
controller 

Sector 

the desired characteris- 
which the floppy disk 
is to be initialized. 

Code 

Density 

Size 

Compatibility 

0 

single 

128 

IBM Diskette 1 

1 

single 

256 

IBM Diskette 2 

2 

single 

512 

— 

3 

double 

256 

IBM Diskette 2D 

4 

double 

512 

Convergent 

5 

double 

1024 

IBM Diskette 2D 

6 

reserved 

— 

— 

7 

double 

256 

Convergent AWS (single- 
sided 5 l/4-in floppy) 

8 

double 

256 

Convergent AWS (double- 


sided 5 l/4-in floppy) 
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Request Block 


Offset 

Field 

Size 
(bytes ) 

contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exehResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

16 

12 

pa ram Code 

2 


14 

reserved 

4 


18 

pbDevSpec 

4 


22 

cbDevSpec 

2 


24 

pbPas sword 

4 


28 

cbPas sword 

2 
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Write 


Description 


The Write operation transfers an integral number 
of 128-, 256-/ 512-/ or 1024-byte sectors from 
memory to disk. Write returns only when the 
requested transfer is complete. The WriteAsync 
and CheckWriteAsync procedures are used to 
overlap computation and input/output transfer. 

To accommodate programming languages in which 
Write is a reserved word, WriteFile is permitted 
as a synonym for the Write service. 

Attempting to write beyond the end of the medium 
results in the return of status code 2 ("End of 
medium" ) . 

Procedural Interface 

Write (fh, pBuffer, sBuffer, lfa, 
psDataRet): ErcType 


where 


fh 


pBuffer 


sBuffer 


lfa 


psDataRet 


is a file handle returned from an 
OpenFile operation. The device must 
be open in modify mode. 

is the memory address of the first 
byte of the buffer from which the 
data is to be written. The buffer 
must be word aligned. 

is the count of bytes to be written 
from memory. It must be a multiple 


of 

or 

the sector 
1024) . 

size (128, 

256, 

512, 

is 

the byte 

offset. 

from 

the 


beginning of the file, of the first 
byte to be written. It must be a 
multiple of the sector size (128, 
256, 512, or 1024) . 

is the memory address of the word to 
which the count of bytes success- 
fully written is to be returned. 
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Request Block 


ssDataRet is always 2. 


Offset 

Field 

Size 
(bytes ) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

36 

12 

fh 

2 


14 

lfa 

4 


18 

pBuf fer 

4 


22 

sBuf fer 

2 


24 

psDataRet 

4 


28 

ssDataRet 

2 

2 
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WriteAsync 

Description 


The WriteAsync procedure initiates the transfer 
of an integral number of 128-, 256-, 512-, or 
1024-byte sectors from memory to disk. The 
CheckWriteAsync procedure must be called to check 
the completion status of the transfer. 

The information returned by Write with its 
psDataRet argument and ErcType status is obtained 
by CheckWriteAsync. 

Procedural Interface 


WriteAsync (fh, pBuffer, sBuffer, lfa, pRq, 
exchangeReply ) : ErcType 


where 

fh 


pBuffer 


sBuffer 


lfa 


pRq 


is a file handle returned from an 
OpenFile operation. The file must 
be open in modify mode. 

is the memory address of the first 
byte of the buffer from which the 
data is to be written. The buffer 
must be word aligned. 

is the count of bytes to be written 
from memory. It must be a multiple 
of the sector size (128, 256, 512, 

or 1024) . 

is the byte offset, from the 
beginning of the file, of the first 
byte to be written. It must be a 
multiple of the sector size (128, 
256, 512, or 1024) . 

is the memory address of a 64-byte 
area to be used as workspace by 
WriteAsync . 


exchangeReply 

is an exchange provided by the 
client process for the exclusive use 
of WriteAsync and CheckWriteAsync. 
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Request Block 


The WriteAsync and CheckWriteAsync procedures are 
procedural interfaces to the Write operation. 
See the Write operation above. 
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22 PRINTER SPOOLER MANAGEMENT 


OVERVIEW 


The printer spooler (simultaneous peripheral 
operation online) management facility provides 
direct and spooled printing to parallel 
(Centronics-compatible) and serial (RS-232C- 
compatible) printer interfaces. 

Direct printing transfers text directly from 
application system memory to a parallel or serial 
printer interface of the local workstation. The 
local printer must be available before direct 
printing is activated. 

In spooled printing , a queue entry is created for 
each printing request and entered in a queue 
managed by the queue manager. A printer spooler 
obtains a queue entry for printing when a printer 
is available. The user need not wait for a 
printer to be available to enter a printing 
request . 

Direct and spooled printing are accessed by the 
printer spooler utilities 'described in the 
"Printer Spooler Utilities Overview" in the 
System Utilities Manual. The reader should be 
familiar with EFiat section before continuing in 
this section. 
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CONCEPTS 


All printer spooler concepts are described in the 
"Printer Spooler Utilities Overview" section in 
the System Utilities Manual. The following 
operations are contained in this section. 

o Conf igureSpooler , which sets or changes the 

printer spooler's configuration, and 

o SpoolerPassword , which sends a file password 
to the printer spooler. 


Printer Spooler Configuration 

When the printer spooler is installed, it reads a 
spooler configuration file designated by the 
user . 

The spooler configuration file at printer spooler 
installation must contain at least the code of 
each printer channel to be controlled by the 
printer spooler. Additional information required 
for each printer can be supplied to the printer 
spooler in either of two ways: 

o in the spooler configuration file at printer 
spooler installation, or 

o dynamically through the Conf igureSpooler 

operation . 

The additional information required for each 
printer is: 

o the name of the printer, 

o the name of the scheduling queue, 

o the printer configuration file specification, 

o the priority of the process that controls the 
printer, and 

o whether to print a banner page at the 

beginning of each file. 
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Sending a Password 


If the security mode is specified in a printing 
request, the printer spooler pauses before 
printing the file and waits for receipt of a 
password. The password can be sent to the 
printer spooler in either of two ways: 

o by the operator invoking the Spooler utility 
and typing the password at the local printer, 
or 

o by a process using the SpoolerPassword 
operation. 
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OPERATIONS: SERVICES 


Printer spooler management provides the 
operations listed below. 

Conf igureSpooler sets or changes the spooler's 

configuration . 

SpoolerPassword sends a file password to the 

printer spooler. 
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ConfigureSpooler 

Description 


The ConfigureSpooler service sets or changes the 
printer spooler's configuration. A printer can 
be added or deleted from a printer spooler. To 
add a printer, the printing queue associated with 
the printer must be defined to the queue manager 
and the printer channel must be defined to the 
printer spooler during the printer spooler's 
installation. 

Procedural Interface 

ConfigureSpooler (channel, pbPrinterName , 

cbPrinterName, pbQueueName, 
cbQueueName, pbConf igureFile , 
cbConf igureFile , priority, 
f Banner): ErcType 

where 

channel is a single-character code that 

specifies the printer channel to 
which the printer is connected: 

0 is the parallel channel 
A is channel A 

B is channel B * 


pbPrinterName 

cbPrinterName 

describe the name of the, printer to 
be added. A 0 means the printer 
connected to the channel is deleted. 

pbQueueName 

cbQueueName describe the name of the scheduling 
queue associated with the printer. 
The name must match a queue name 
defined for the system. 

pbConf igureFile 
cbConf igureFile 

describe the file specification of 
the printer configuration file. 
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priority 


is the priority (10-24, with 10 the 
highest) of the printer spooler's 
control process for the printer. A 
priority lower than 128 (the default 
priority of the user program) 

ensures that the printer spooler 
does not impact the user program. 

fBanner is a flag that indicates whether a 

banner page is to be printed at the 
beginning of each file. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

3 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

188 

12 

channel 

1 


13 

pbPrinterName 

4 


17 

cbPrinterName 

2 


19 

pbQueueName 

4 


23 

cbQueueName 

2 


25 

pbConf igureFile 4 


29 

cbConf igureFil 

e 2 


31 

priority 

1 


32 

fBanner 

1 


33 

reserved 

3 
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SpoolerPas sword 
Description 

The SpoolerPas sword service sends a file password 
to the printer spooler. If the printer spooler 
is in the security mode, it waits for the 
password before it proceeds to open and read the 
protected file. 

Procedural Interface 


SpoolerPas sword (pbPrinterName, cbPrinterName, 

pb Pas sword, cbPas sword): ErcType 

pbPrinterName 

cbPrinterName describe the name of the 

printer . 

pb Pas sword 

cbPassword describe the password. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

2 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

189 

12 

reserved 

6 


18 

pbPrinterName 

4 


22 

cbPr i nt e rName 

2 


24 

pb Pas sword 

4 


28 

cbPassword 

2 
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23 VIDEO MANAGEMENT 


OVERVIEW 


Th e video subsystem provides a highly flexible 
means for the display of alphanumeric and 
(limited) graphic information by the application 
system in the primary application partition. The 
video hardware uses DMA to continuously refresh 
the image on the screen, thus ensuring a flicker- 
free image. The video hardware reads characters 
and attributes from memory. It then converts 
them from the extended ASCII (8-bit) memory 
representation to a pattern of illuminated dots 
(pixels) that it displays on the screen. During 
this conversion, the video hardware references a 
translation table (font) that is part of the 
video hardware. In some models of workstation, 
the font can be modified by software. 


Video Attributes 


Video attributes control the visual presentation 
of characters on the screen. There are three 
kinds of video attributes: screen, line, and 

character . 

° Screen attributes control the presentation of 
the entire screen. Examples are blank, 
reverse video (dark characters on a light 
background), half-bright, number of 
characters per line (80 or 132), and the 
presence or absence of character attributes." 

° Li ne attributes control the presentation of a 
single line. Examples are cursor position, 
double-height characters, and double-width 
characters . 

° Character attributes control the presentation 
of a single character. Examples are reverse 
video, blinking, half-bright, underlining, 
bold, superscript, and subscript. 
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Video Software 


The video software provides several features 
(multiple frames, scrolling of each frame) that 
enhance the capabilities of the video 

subsystem. To the video software, the screen 
consists of a number of separate, rectangular 
areas called frames . A frame can have any 
desired height and width (up to those of the 
entire screen) . Each frame can be scrolled up or 
down independent of other frames. 


Hierarchy of Video Software 

Three levels of video software control the video 

subsystem: 

o Video Display Management (VDM) . The Video 

Display Management facility provides direct 
control over the video hardware. 

o Video Access Method (VAM) . The Video Access 

Method provides direct access to the 
characters and character attributes of each 
frame. The Video Access Method includes 
explicit control of scrolling. 

o Sequential Access Method (SAM). The 

Sequential Access Method provides device- 
independent access to devices such as the 
printer, files, keyboard, as well as the 
video display. The Sequential Access Method 
provides automatic scrolling. Video— specif ic 
extensions to the Sequential Access Method 
provide direct cursor addressing, control of 
character attributes, etc. 
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CONCEPTS 


Video Capabilities 

The several models of workstation have different 
video capabilities: basic, standard, or 
advanced . 

Users who access the video subsystem at the Video 
and Sequential Access Method levels (but not the 
Video Display Manager level), and who only use 
the basic video capability, are assured 
compatibility among the different models. 


Basic 

Basic video capabilities are provided by the AWS 
workstation. These capabilities are 
characterized by an 80-character by 28-line 
screen, one cursor on the screen, a 256 character 
set that cannot be modified by software, and a 
screen split horizontally into multiple frames. 


Standard 

Standard video capabilities are provided by the 
IWS family of workstations. These capabilities 
are characterized by a 34-line screen, a 
software-selectable 80- or 132-character line, 
one cursor per line, a 256 character set that can 
be dynamically modified by software, and a screen 
split horizontally and/or vertically into 
multiple frames that can overlap each other. 


Advanced 


Advanced video capabilities are provided by the 
IWS family of workstations with an optional board 
added to the standard video board. Several 
versions of this optional board provide various 
capabilities (for example, bold, double-height 
characters, double-width characters, or a 512 
character set) that augment the standard video 
capabilities of the IWS workstation. 
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Standard Video Capability 


Characters displayed on the screen are stored in 
a contiguous area called the character map . The 
physical memory address and size of the character 
map are loaded into the video DMA channel. The 
character map must start at a word boundary and 
must be completely contained in the first 128k 
bytes of memory. There is a default 6800-byte 
character map in the System Image. Alterna- 
tively, the application system in the primary 
application partition can relocate the character 
map to an area of long-lived memory it allocated. 

The size of this character map depends on: 

o the number of characters per line (80 or 
132) , 

o the number of lines per screen (1 to 34), and 

o the presence or absence of character 

attributes . 


Video Attributes 


Video attributes control the visual presentation 
of characters on the screen. The three kinds of 
video attributes are screen, line, and character. 


Screen Attributes . Screen attributes control the 
presentation of the entire screen. The screen 
attributes, specified in the Screen Attribute 
Register in the video hardware, are blank, 
reverse video (dark characters on a light 
background), half-bright, number of characters 
per line (80 or 132), and the presence or absence 
of character attributes. The number of lines (1 
to 34) displayed on the screen is determined 
implicitly by the size of the character map 
loaded into the video DMA register. 


Line Attributes. Line attributes control the 
presentation of a single line. They are 
specified in the character map in the word that 
precedes the first character of the line. The 
standard line attribute is cursor position. 
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Character Attributes. Character attributes 
control the presentation of a single character. 
Character attributes can be present or absent, 
depending on the value of a screen attribute. If 
character attributes are present, then each 
character has a 4-bit character attribute 
field. The 4-bit character attribute field 
specifies the presence or absence of four 
attributes: reverse video, blinking, half- 
bright, and underlining. 


Video Refresh 


The video hardware continuously refreshes the 
image on the screen, thus ensuring a flicker-free 
image. Video refresh is a hardware function that 
reads (using DMA) characters and line and 
character attributes from the character map in 
memory. It then converts them from the extended 
ASCII (8-bit) memory representation to a 10 by 15 
bit array, and displays these bits on the screen 
as a pattern of illuminated dots (pixels ) . 


Font RAM. During the conversion from a memory 
representation to a bit array, the standard video 
hardware references a translation table (font) 
located in the font RAM. The font RAM, part of 
the video hardware, contains a 10 by 15 bit array 
for each of the 256 characters in the character 
set. The font RAM can be modified by software. 


Advanced Video Capability 

Additional features (beyond the standard video 
capability) provided by the advanced video #1 
capability are a cursor RAM, a style RAM, the 
double-height and double-width line attributes, 
and the bold, superscript, and subscript 
character attributes. 


Cursor RAM 


A cu f sor RAM allows software to specify a 10 by 
15 bit array and display these bits as a pattern 
of pixels in place of the standard cursor (a 
blinking underline). The cursor bit array is 
superimposed on the character and blinks. 
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Style RAM 


To allow access to the additional character 
attributes, the 4-bit character attribute field 
is interpreted as an index into the style RAM. 
The style RAM contains 16 entries, each of which 
specifies the presence or absence of each of the 
video attributes. 


Basic Video Capability 

The AWS workstation has basic video capability 
only, in contrast to the standard or advanced 
video capability of the IWS workstation. 

Characters displayed on the screen are stored in 
a contiguous area of memory called the character 
map. The physical memory address and size of the 
character map are loaded into the video DMA 
channel. The character map must be completely 
contained in the first 64k bytes of memory. 
There is a default 2784-byte character map _ in the 
System Image. Alternatively, the application 
system can relocate the character map to an area 
of long-lived memory that it allocated. The size 
of this character map depends on the number of 
lines per screen (1 to 28). 


Video Attributes 


Video attributes control the visual presentation 
of characters on the screen. The two kinds of 
video attributes are screen and character. 


Screen Attributes. Screen attributes control the 
presentation of the entire screen. Screen 
attributes, processed by the video software, are 
blank, reverse video (dark characters on a light 
background), half— bright, and cursor position. 
The number of lines (1 to 28) displayed on the 
screen is determined implicitly by the size of 
the character map loaded into the video DMA 
register . 


Character Attributes. Character attributes 

control the presentation of a single character. 
Character attributes are 8-bit bytes that are 
embedded in the character map and specify the 
presence or absence of five attributes: reverse 
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video, blinking, half-bright, underlining, and 
special character. Character attributes are 
identified by having their high-order bit set and 
are limited to 16 per line. The special 
character attribute is used to display character 
codes 80h to OFFh. 


Video Refresh 


The video hardware continuously refreshes the 
image on the screen, thus ensuring a flicker-free 
image. Video refresh is a hardware function that 
reads ( using DMA) characters and character 
attributes from the character map in memory. It 
then converts them to a 9 by 11 bit array, and 
displays these bits on the screen as a pattern of 
illuminated dots (pixels ) . 


Font ROM. During the conversion from a memory 
representation to a bit array, the basic video 
hardware references a translation table (font) 
located in the font ROM. The font ROM , part of 
the video hardware, contains a 9 by 11 bit array 
for each of the 256 characters in the character 
set . 


Video Software 


The video software provides several features 
(multiple frames, scrolling of each frame) that 
enhance the capabilities of the video 
subsystem. To the video software, the screen 
consists of a number of separate, rectangular 
areas called frames . A frame can have any 
desired height and width (up to those of the 
entire screen) . The number of frames supported 
is a parameter supplied at system build; the 
default is 8. Each frame can be scrolled up or 
down independent of other frames . 


Hierarchy of Video Software 

Three levels of video software control the video 
subsystem: the Video Display Manager, the Video 
Access Method, and the Sequential Access Method. 
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Video Display Management 


The Video Display Management (VDM) provides 
direct control over the video hardware. With it, 
an application system can: 

o determine the level of video capability 

present, 

o load a new character font into the font RAM, 

o change screen attributes, such as reverse 

video and half-bright, while the screen is 
being video-refreshed, 

o stop video refresh (this is useful when 

moving or changing the size of the frames or 
the character map) , 

o calculate the amount of memory needed for the 
character map based on the desired number of 
columns and lines, and the presence or 

absence of character attributes, 

o initialize each of the frames, and 

o initialize the character map. 

Once the character map is initialized and video 
refresh is started, the image on the screen is 
controlled by modifying the characters and 
attributes stored in the character map. This is 
best accomplished using the system common 
procedures of the Video Access Method and the 
object module procedures of the Sequential Access 
Method. If necessary, however, an application 
system in the primary application partition can 
manipulate the image on the screen by writing 
directly into the character map. This is 
somewhat more efficient than using the procedures 
of the Video and Sequential Access Methods, but 
results in code that is not compatible among the 
several models of workstation. 


Video Access Method 

The Video Access Method (VAM) provides direct 
access to the characters and character attributes 
of each frame. The operations of VAM can: 

o put a string of characters anywhere in a 
frame , 
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o specify character attributes for a string of 
characters , 

o scroll a frame up or down a specified number 
of lines, 

o position a cursor in a frame (each frame can 
have its own cursor except in workstations 
having only basic video capability) , and 

o blank a frame (that is, set all character 
positions to blank, reset all character 
attributes, and eliminate any visible cursor 
from the frame). 

The Video Access Method consists of a set of 

system common procedures. 


Sequential Access Method 

The. Sequential Access Method (SAM) provides 
device-independent access to devices such as the 
printer, files, keyboard, as well as the video 
display. The video byte stream extensions to the 
Sequential Access Method support multiple frames, 
character attributes, and explicit positioning of 
characters in a frame, but do not support line 
attributes (other than cursor position). The 
Sequential Access Method recognizes a few special 
cursor-positioning characters including RETURN, 
NEXT PAGE, BACKSPACE, and TAB. When a special 
character or full line would cause the cursor tp 
move below the bottom line of the frame, the 
Sequential Access Method automatically scrolls 
the frame and repositions the cursor. 


Application System/video Subsystem Interaction 

To eliminate the need for user programming to 
support video display initialization, the 
Convergent Executive performs initialization 
before invoking an application system. (See the 
Executive Manual . ) It also allows the 

workstation operator to use the Screen Setup 
command to respecify these video characteristics: 

o reverse video, 

o number of characters per line (80 or 132), 
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o number of lines (1 to 34), and 

o the presence or absence of character 
attributes . 

When an application system is invoked, it 
inherits the character font, the character map 
(in system memory) , and two frames (Command Frame 
and Status Frame) from the Executive. Video 
refresh continues and the image on the screen 
remains unchanged. 

The application system can now update the image 
on the screen by using the Video or Sequential 
Access Methods or by directly manipulating the 
content of the area of memory containing the 
character map. 

The application system needs to use the 
operations of the Video Display Management 
facility only if the character font, screen size, 
frames, or provision for character attributes 
must be changed during the execution of the 
application system. 


Video Control Block 

The Video Control Block (VCB) contains all 
information known to the OS about the video 
display, including the location, height, and 
width of each frame, and the coordinates at which 
the next character is to be stored in the frame 
by the Sequential Access Method. The VCB is 
located in system memory at an address recorded 
in the System Common Address Table. The VCB is 
described in more detail below. 
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SYSTEM DATA STRUCTURES: THE VIDEO CONTROL BLOCK AND FRAME 
DESCRIPTOR 

This section should be read after the "Video 
Display Management" and "Video Access Method" 
sections . 

The Video Control Block (VCB) contains all 
information known about the video display, 
including the location, height, and width of each 
frame, and the coordinates at which the next 
character is to be stored in the frame by the 
Sequential Access Method. The VCB is located in 
system memory at an address recorded at address 
244h in the System Common Address Table. The 
content of the VCB is shown in Table 23-1 below. 

The Video Control Block contains an array of 
frame descriptors. A frame descriptor is a 
component of the VCB and contains all information 
known about one of the frames. The number of 
frame descriptors in the VCB is specified at 
system build. The content of a frame descriptor 
is shown in Table 23-2 below. 
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Table 23-1. Video Control Block. 


Offset 

Field 

Size 
(bytes ) 

0 

level 

1 

1 

fCharAttrs 

1 

2 

f Re verse Video 

1 

3 

fHalfBright 

1 

4 

pMap 

4 

8 

sMap 

2 

10 

cFrames 

1 

11 

cColsMax 

1 

12 

cLinesMax 

1 

13 

sLine 

1 

14 

ibToAttrs 

1 

15 

ibToChars 

1 

16 

bSpace 

1 

17 

SAR 

2 

19 

pRgfLineDirty 

4 

23 

pRgbRuns 

4 

27 

iFrameCursor 

1 

28 

pRgbRunsVirgin 

4 

32 

rgbRgFrame 

* 

*20 bytes for each frame defined at 

system 

build . 




where 


level 


is the level of video capability: 


0 = standard; 

1 = advanced #1; 

2 = basic; 

3 = advanced #2. 

Other values will identify future 
capability levels. It is set by the 
QueryVidHdw and ResetVideo 

operations . 

fCharAttrs is TRUE if the character map 
includes character attributes and 
the use of character attributes is 
enabled in the Screen Attribute 
Register in the video hardware. It 
is FALSE otherwise. The fAttr 
parameter to the ResetVideo 
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operation is placed here. It is set 
by the ResetVideo operation. 


f ReverseVideo 


fHalfBright 


pMap 

sMap 


cFrames 


cColsMax 

cLinesMax 


sLine 


is TRUE if the screen reverse video 
is enabled in the Screen Attribute 
Register in the video hardware. 
This causes the hardware to display 
dark characters on a light 
background. It is FALSE other- 

wise. It is initialized by the 
ResetVideo operation to FALSE and 
can be changed by the SetScreenVid- 
Attr operation. 

is TRUE if screen half-bright is 
enabled in the Screen Attribute 
Register in the video hardware. 
This causes the hardware to display 
at half-bright. It is FALSE other- 
wise. It is initialized by the 
ResetVideo operation to FALSE and 
can be changed by the SetScreenVid- 
Attr operation. 


are the memory address and size of 
the character map, which are 
provided as parameters to the 
InitCharMap operation. 

is the number of frames. This 
number is established at system 
build. The default is 8. 


are the height and width of the 
screen. These values are used by 
the InitVidFrame operation to verify 
frame coordinates and dimensions. 
They are set by the ResetVideo 
operation. 

is the total number of bytes 
required to contain all the 
information for one line of the 
character map. This information 
includes line attributes, filler 
bytes needed by the video hardware, 
text characters, and character 
attributes (if specified). This 
field can be multiplied by the 
number of a line to compute the 
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offset from pMap of the first byte 
of the line. It is set by the 
ResetVideo operation. 

NOTE: The information given for the next two 

fields, ibToAttrs and ibToChars, is not 
meaningful for workstations with only basic video 
capability. Dependence on this information will 
result in software that is not compatible among 
workstation models. 

ibToAttrs is the number of bytes from the 
start of a line in the character map 
to the first byte of character 
attributes (this is only valid if 
fCharAttrs = TRUE). To compute the 
offset (from the beginning of the 
character map) of the character 
attribute field for the character at 
column iCol and line iLine : 

1. multiply iLine by the sLine 
field of the VCB, 

2. add the ibToAttrs field of the 
VCB, and 

3. add the integer quotient of iCol 
divided by 2. 

The character attributes for even 
column numbers are in bits 0-3 (low- 
order nibble) and for odd column 
numbers in bits 4-7 (high-order 
nibble). It is set by the Reset- 
Video operation. 

ibToChars is the number of bytes from the 
start of a line in the character map 
to the character 0 of the line. To 
compute the offset (from the 
beginning of the character map) of 
the character displayed at screen 
coordinates iLine and iCol : 

1. multiply iLine by the sLine 
field of the VCB, 

2. add the ibToChars field of the 
VCB, and 

3 . add iCol . 

It is set by the ResetVideo 
operation . 
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bSpace is the 8-bit character code that 

displays an empty character position 
on the screen. This code is 0 
(null) in the standard Convergent 
font. The bSpace field of the VCB 
is set from a parameter to the 
ResetVideo operation and is used by 
the InitCharMap, ResetFrame, and 
ScrollFrame operations. 

SAR is an exact copy of the 16 bits that 

were last loaded into the Screen 
Attribute Register. 


pRgfLine Dirty 

is the memory address of an array of 
28 flags (bytes), one flag for each 
line. Each flag indicates whether 
or not video attributes are 
intermixed with the characters on 
that line (AWS workstations only). 

pRgbRuns is the memory address of an array of 

16 x 28 words. The low-order byte 
of each word describes an attribute, 
and the high-order byte specifies 
the number of characters to which 
the attribute applies. Sixteen 
words are used to describe each line 
on the video display (AWS 
workstations only) . 


iFrameCursor 

stores the number of the frame in 
which the cursor is located. This 
field is updated whenever PosFrame- 
Cursor is called (AWS workstations 
only) . 

pRgbRuns Virgin 

is the memory address of an array of 
16 words. The contents of this 
array represent a line that does not 
have attributes intermixed with the 
characters (AWS workstations only). 

rgbRgFrame is the array of frame descriptors . 

It is set by the InitVidFrame 
operation and cleared by the 
ResetVideo operation. 
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Table 23-2. Frame Descriptor. 


Offset 

Field 

0 

iLineStart 

1 

iColStart 

2 

cLines 

3 

cCols 

4 

iLineLef tOf f 

5 

iColLeftOf f 

6 

bBorderDesc 

7 

bBorderChar 

8 

bBorderAttr 

9 

iLinePause 

10 

iLineCursor 

11 

iColCursor 

12 

fDblWide 

13 

fDblHigh 

14 

reserved 


Size 
(bytes ) 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

1 

6 


where 


iLineStart 

iColStart 


are the vertical and horizontal 
screen coordinates of the upper left 
corner of the frame. This is where 
a character would go if the 
PutFrameChars operation were called 
with iLine and iCol = 0. 


cLines 

cCols 


is the height and width of the 
frame. In the case of a frame being 
used on video hardware that provides 
the double-height and double-width 
line attributes and for which the 
fDblWide flag in the frame 
descriptor is set to TRUE, this 
field can only be half as large as 
otherwise possible (for example, 40 
instead of 80, or 66 instead of 
132) . 

Double— he ight and double— width 
frames cannot share any line with 
single-height and single-width 

frames . 


23-16 


CTOS” Operating System Manual 




iLineLeftOf f 
iColLeftOf f 


bBorderDesc 


bBorderChar 


bBorderAttr 


iLinePause 


Double-height frames use up two 
times cLines screen lines, although 
they do not affect the sMap field of 
the VCB or the computations for 
placing characters or character 
attributes in the character map. 
For example, if a screen consists of 
only one frame and that frame is 
double-height, it can be at most 17 
lines high, since twice 17 is 34, 
the maximum number of lines . 


is used by the Sequential Access 
Method to record the coordinates at 
which the next character is to be 
stored in the frame. The presence 
of this information in the VCB 
allows a succeeding application 
system to append to information 
displayed by its predecessor. 

is a byte with bits 0-3 specifying a 
border just outside the frame on the 
corresponding side. 

Bit Side 

0 Top 

1 Right 

2 Bottom 

3 Left 

The border is drawn when the 
InitCharMap operation is executed. 
The same character with the same 
character attributes (see the 
bBorderChar and bBorderAttr 
parameters of the InitVidFrame 
operation) is used for all sides and 
corners . 

is the character to use for borders 
when the InitCharMap operation is 
executed. 

is the character attribute to use 
for borders when the InitCharMap 
operation is executed. 

is used by the Sequential Access 
Method to determine when to prompt 
the workstation operator to press 
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the NEXT PAGE key after a new page 
of text is scrolled onto the 
screen. iLinePause indicates which 
line (0-33) is "marked." iLinePause 
is decremented whenever the marked 
line is scrolled upward. When it is 
decremented to 0, a message 
prompting the user is displayed. 
(See the complete description of 
this in the subsection on 
"Automatically Pausing Between Full 
Frames of Text" in the "Sequential 
Access Method" section.) If 

iLinePause is set to 255 (OFFh), as 
it is by the ResetFrame operation, 
the functions described above are 
suppressed . 

iLineCursor 

iColCursor are the vertical and horizontal 
coordinates within the frame at 
which the visible cursor is 
displayed. If iLineCursor and 

iColCursor are each set to 255 
(OFFh), there is no visible cursor 
in the frame . 


fDblWide 

is TRUE 

for 

double-width 


characters . 

It 

is FALSE 


otherwise . 

It is 

ignored on 


workstations 
#1 capability 

without advanced video 

• 

fDblHigh 

is TRUE 

for 

double-height 

characters . 

It 

is FALSE 


otherwise . 

It is 

ignored on 


workstations without advanced video 
#1 capability. Frames of double- 
height characters must be 
anticipated when the ResetVideo 
operation is called. The nLines 
parameter to ResetVideo must be 
reduced by one for every screen line 
that is double-height. 
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24 VIDEO DISPLAY MANAGEMENT 


OVERVIEW 


11,516 vj - deo Display Management (VDM) facility 
provides direct control over the video 

hardware. With it, the application system in the 
primary application partition can: 

o determine the level of video capability 

present (basic, standard, and advanced video 
capabilities are described in the "Video 
Management" section), 

o load a new character font into the font RAM, 

o stop video refresh (useful when moving or 

changing the size of the frames or the 
character map), 

o change screen attributes, such as reverse 

video and half-bright, while the screen is 
being video-refreshed, 

o calculate the amount of memory needed for the 
character map based on the desired height and 
width of the characters, and the presence or 
absence of character attributes, 

o initialize each of the frames, and 

o initialize the character map. 

Once the character map is set up and video 
refresh is started, the image on the screen is 
controlled by modifying the characters and 

attributes stored in the character map. This 
manipulation is best accomplished using the 
system common procedures of the Video Access 
Method and the object module procedures of the 
Sequential Access Method. If necessary, however, 
the application system in the primary application 
partition can manipulate the image on the screen 
by. writing directly into the character map. 
Writing directly is somewhat more efficient than 
using the procedures of the Video and Sequential 
Access Methods, but results in code that is not 
compatible among the several models of 
workstation . 
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CONCEPTS 


Reinitializing the Video Subsystem 


The varied capabilities of the video subsystem 
are initialized by a sequence of software 
operations. The application system in the 

primary application partition needs to 
reinitialize the video subsystem only if the 
desired state is not a capability of the Screen 
Setup command (described in the Executive 
Manual.) An application system that 

reinitializes the video subsystem must include a 
sequence of software operations similar to the 
following. The application must: 

1. use the QueryVidHdw operation to determine 
the level of video capability present on the 
workstation in use . 

2. use the LoadFontRam operation to read the 
character font from a file to memory and then 
load this font into the font RAM, except in 
workstations having only the basic video 
capability. In workstations having advanced 
video #1 capability, the application system 
must load the cursor RAM and the style RAM 
using the LoadCursorRam and LoadStyleRam 
operations . 

3. use the ResetVideo operation to place the 
following information in the Video Control 
Block (described in the "Video Management" 
section) : 


o 

number of characters per 
132) , 

line 

(80 

or 

o 

number of lines per screen 

(1 to 

34), 

and 

o 

the presence or absence 
attributes . 

of character 


4. allocate a long-lived memory segment to use 
as the character map, if the use of the 
character map in system memory is 
unsatisfactory. When calling the 

AllocMemoryLL operation, the application 
system should specify the size computed by 
the ResetVideo operation. (See the "Memory 
Management" section.) 
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5. use the InitVidFrame operation to specify the 
screen coordinates and dimensions of one of 
the frames . 

6. use the SetScreenVidAttr operation to set 
reverse video or half-bright, if desired. 

7. use the InitCharMap operation to initialize 
the character map. 

8. use the SetScreenVidAttr operation to 
initiate video refresh. 

The application system can now display 
information by using the Video or Sequential 
Access Methods or by writing characters and 
attributes directly into the character map. 
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OPERATIONS : SERVICES 


The Video Display Management facility provides 

the operations listed below. 

InitCharMap initializes the character map. 

InitVidFrame defines the screen coordinates 

and dimensions of one of the 
frames . 

LoadCursorRam moves cursor pixel information 

from the specified memory area 
to the cursor RAM. 

LoadFontRam reads the character font from 

the specified open file to the 
specified memory area and then 
transfers the font to the font 
RAM. 

LoadStyleRam moves style (character 

attribute) information from the 
specified memory area to the 
style RAM. 

QueryVidHdw places information describing 

the level of video capability 
of the workstation in the 
specified memory area. 

ResetVideo suspends video refresh, resets 

all screen attributes, and 
changes the values stored in 
the Video Control Block to 
reflect the specified 
parameters . 

SetScreenVidAttr sets/resets a specified screen 

attribute . 
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InitCharMap 

Description 


The InitCharMap service initializes the character 
map. The ResetVideo and InitVidFrame operations 
must be called first. 

InitCharMap sets all character positions of the 
character map to blanks and resets all line and 
character attributes. It then places the border 
character at the character positions that define 
the border of the frames for which borders were 
requested. The border descriptor, border 

character, and border attributes of each frame 
are specified by the InitVidFrame operation and 
are stored in a frame descriptor of the Video 
Control Block. (The Video Control Block and 
frame descriptor are described in the "Video 
Management" section.) 

Procedural Interface 

InitCharMap (pMap, sMap) : ErcType 

where 

pMap is either 0 to indicate the use of 

the character map in system memory 
or is the memory address of a 
character map in long-lived memory. 

sMap is the size of the character map. 
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Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

76 

12 

reserved 

6 


18 

pMap 

4 


22 

sMap 

2 
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InitVidFrame 


Description 

The InitVidFrame service defines the screen 
coordinates and dimensions of one of the 
frames. InitVidFrame must be called at least 
once after the ResetVideo operation and before 
the InitCharMap operation is called. It can also 
be called while the video subsystem is in use to 
change a frame or to add a frame. The Video 

Control Block is updated to reflect the changed 
or added frame. {The Video Control Block and 

frame descriptor are described in the "Video 
Management" section.) 

The screen coordinates of the upper left corner 
of the frame are specified by iColStart and 
iLineStart. The width and height of the frame 
are given by nCols and nLines, respectively. 
Frames can overlap, but they cannot exceed the 
screen dimensions. 

Procedural Interface 

InitVidFrame (iFrame, iColStart, iLineStart, 
nCols, nLines, borderDesc, 
bBorderChar, bBorderAttr, 
fDblHigh, fDblWide): ErcType 

where 

iFrame is an integer that ranges from 0 to 

the number of frame descriptors in 
the Video Control Block minus 1. 
This identifies the frame to be 
acted upon and selects one of the 
frame descriptors of the Video 
Control Block for modification. 

iColStart is the column of the screen that 
corresponds to the leftmost column 
of the frame . 

iLineStart is the line of the screen that 

corresponds to the top line of the 
frame . 

nCols is the width of the frame in 

columns . 


Video Display Management 24-7 



nLines 


borderDesc 


bBorderChar 

bBorderAttr 


f DblHigh 
f DblWide 


is the height of the frame in 
lines. Note that if the frame is 
double-height (or double-width), 
nLines (or nCols) can only be half 
as large as otherwise possible. 

is a byte with bits 0-3 specifying a 
border just outside the frame on the 
corresponding side. Note that the 
border characters are in addition to 
the area defined by nCols and 
nLines . 

Bit Side 

0 Top 

1 Right 

2 Bottom 

3 Left 

The border is drawn when the 
InitCharMap operation is executed. 
The same character and attributes 
(bBorderChar and bBorderAttr) are 
used for all sides and corners. 
Left and right borders are not 
permitted in workstations with only 
basic video capability. 

specifies the character code to use 
for the frame borders when drawn by 
the InitCharMap operation. 

specifies the 4-bit character 
attribute field with which 

bBorderChar is to be displayed. 

To create complex borders, including 
corner characters, initialize a 
frame that defines the entire 
screen; then put the appropriate 
border characters and attributes 
into the character map (using the 
PutFrameChars and PutFrameAttrs 
operations; see the "Video Access 
Method" section) . 

is TRUE if the frame is to display 
all double-height characters. 

is TRUE if the frame is to display 
all double-width characters. 
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fDblHigh and fDblWide are only 
meaningful on workstations having 
advanced video #1 capability. If 
fDblHigh is TRUE, then the nLines 
parameter can only be half as large 
as in a frame with normal height 
characters. If fDblWide is TRUE, 
then (1) nCols can only be half as 
large as in a frame with normal 
width characters, and (2) iColStart 
must be an even number. See the 
frame descriptor format in the 
"Video Management" section for more 
information. 

Note that since double-height and 
double-width are line attributes, 
frames that are double-height or 
double-width cannot share any line 
with frames that are not also 
double-height or double-width. 


Video Display Management 24-9 



Request Block 


Size 

Offset Field (bytes) Contents 


0 

sCntlnfo 

2 

2 

nReqPbCb 

1 

3 

nRespPbCb 

1 

4 

userNura 

2 

6 

exchResp 

2 

8 

ercRet 

2 

10 

rqCode 

2 

12 

iFrame 

1 

13 

iColStart 

1 

14 

iLineStart 

1 

15 

nCols 

1 

16 

nLines 

1 

17 

borderDesc 

1 

18 

bBorderChar 

1 

19 

bBorderAttr 

1 

20 

fDblHigh 

1 

21 

fDblWide 

1 
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Load Cursor Ram 


Description 

The LoadCursorRam service moves 16 words (32 
bytes) of cursor pixel information from the 
specified memory area to the cursor RAM. Word 15 
of the 16-word entry must be 0; words 0 to 14 
represent the 15 rows of the cursor from top to 
bottom (note that this is offset 1 word from the 
layout of a character in the font RAM) . Only 

bits 9 to 0 (where bit 0 is the least 
significant) of each word are used and represent 
the pixels from left to right. 

LoadCursorRam only has effect in a video 
subsystem with advanced video #1 capability. 

Procedural Interface 

LoadCursorRam (pCursor, sCursor) : ErcType 
where 

pCursor is the memory address of the cursor 

pixel information. 


Request Block 


sCursor is always 32. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

24 

12 

reserved 

6 


18 

pCursor 

4 


22 

sCursor 

2 

32 
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LoadFontRam 


Description 

The LoadFontRam service reads the character font 
from the specified open file to the specified 
memory area and then transfers the font to the 
font RAM. The file must contain a 16-word entry 
for each of 256 characters. Thus the file is 
exactly 4096 words (8192 bytes) long. Word 0 of 
each 16-word entry must be 0; words 1 to 15 
represent the 15 rows of the character from top 
to bottom. Only bits 9 to 0 (where bit 0 is the 
least significant) of each word are used and 
represent the pixels from left to right. 

LoadFontRam only has effect in a video subsystem 
with standard or advanced video capabilities. 

Procedural Interface 

LoadFontRam (fh, pBuffer, sBuffer) : ErcType 
where 

fh is the file handle of an open file 

containing the character font. 

pBuffer is the memory address of the buffer 

to use in loading the font RAM. 

sBuffer is 8704. pBuf fer/sBuf fer describe 

the memory area to be used by 
LoadFontRam. The memory area must 
be completely contained in the first 
128k bytes of memory and its size 
must be 8704 bytes. 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Content 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

22 

12 

fh 

2 


14 

reserved 

4 


18 

pBuf fer 

4 


22 

sBuf fer 

2 

8704 
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LoadStyleRam 

Description 


The LoadStyleRam service moves 16 words (32 
bytes) of style information from the specified 
memory area to the style RAM. Each word contains 
attribute bits that are selected by the 4-bit 
character attribute field in the character map. 
See the Workstation Hardware Manual for the 
format of the style information. 

LoadStyleRam only has effect in a video subsystem 
with advanced video #1 capability. 

Procedural Interface 

LoadStyleRam (pStyle, sStyle): ErcType 

where 

pStyle is the memory address of the style 

information. 


Request Block 


sStyle is always 32. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

23 

12 

reserved 

6 


18 

pStyle 

4 


22 

sStyle 

2 

32 


24-14 


CTOS" Operating System Manual 




QueryVidHdw 

Description 


The QueryVidHdw service places information 
describing the level of video capability of the 
workstation in the specified memory area. When 
writing software that must work on several models 
of workstations, use QueryVidHdw to determine the 
level of video capability present before calling 
the ResetVideo operation. The format of the 
returned data is shown below. 
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Offset 

Field 

Size 

(bytes) 

Description 

3 

nColsWide 

1 

Wider line width 
(for example, 
132) . 

4 

bitMapLevel 

1 

Level of bit map 
capability: 

0 = none; 

1 = for IWS work- 
stations . 

5 

nPixelsHigh 

2 

Number of pixels 
high for this 
version of bit 
map. 

7 

nPixelsWide 

2 

Number of pixels 
wide for this 
version of bit 
map . 

9 

saGraphicsBoard 2 

Only applies if 
bit map level is 
1. Segment 
address of 64k 
memory segment 
assigned to 
Graphics Multibus 
Board . 

11 

ioPort 

2 

Only applies if 
bit map level is 
1. This is the 
switch-selectable 
input/output port 
used to select a 
64k segment 
within the 
Graphics Multibus 
Board memory. 

13 

reserved 

87 
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Procedural Interface 


QueryVidHdw (pBuffer, sBuffer) : ErcType 
where 

pBuffer is the memory address of the buffer 

to which the video capability 
information is to be copied. 

sBuffer is the size of the buffer. If 

sBuffer is too small, the data is 
truncated. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

21 

12 

reserved 

6 


18 

pBuffer 

4 


22 

sBuffer 

2 
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ResetVideo 


Description 


The ResetVideo service suspends video refresh, 
resets all screen attributes, and changes the 
values stored in the Video Control Block to 
reflect the specified parameters. Subsequent 
calls to the InitVidFrame operation are validated 
against the values in the Video Control Block. 
(The Video Control Block is described in the 
"Video Management" section.) 

Any number of columns or lines can be specified 
if the video hardware permits specification of an 
equal or greater number of columns or lines. For 
example, a screen of 105 columns can be specified 
on a video subsystem that has an 80-column mode 
and a 132-column mode. In this case, the mode 
would be set to 132-column mode, the leftmost 105 
columns would be used, and the rightmost 27 
columns would be blank. 


Three values (sLine, ibToAttrs, and ibToChars ) 
are calculated and stored in the Video Control 
Block for the Video Access Method or equivalent 
user code . The rest of the Video Control Block 
is reset, notably the definitions of all 
frames. Also, the fExecScreen flag in the 
Application System Control Block is set to FALSE. 

Procedural Interface 


ResetVideo (nCols, nLines, fAttr, bSpace, 
psMapRet): ErcType 

where 

nCols specifies the number of characters 

per line (1 to 132). 

nLines specifies the number of lines per 

screen (1 to 34) . 

fAttr specifies whether the character map 

is to include character 

attributes. It is TRUE if character 
attributes are to be used; it is 
FALSE otherwise. 


bSpace specifies a character code that is 

blank in the font. This is used 
when the character map is 
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initialized by the InitCharMap 
operation, and by the ResetFrarae and 
ScrollFrame operations. (See the 
"Video Access Method" section) . 

psMapRet is the memory address of the word to 

which the required size of the 
character map is returned. 

Request Block 

ssMapRet is always 2. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

74 

12 

nCols 

1 


13 

nLines 

1 


14 

f Attr 

1 


15 

bSpace 

1 


16 

reserved 

2 


18 

psMapRet 

4 


22 

ssMapRet 

2 

2 
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SetScreenVidAttr 


Description 


The SetScreenVidAttr service sets and resets a 
specified screen attribute. 


Procedural Interface 


SetScreenVidAttr (iAttr, fOn) : ErcType 


where 

iAttr 


fOn 


identifies the screen attribute. 


Value 


Screen Attribute 


0 reverse video 

1 video refresh 

2 half-bright 


is TRUE to turn the specified screen 
attribute on and FALSE to turn it 
off. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

77 

12 

iAttr 

2 


14 

fOn 

2 
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25 VIDEO ACCESS METHOD 


OVERVIEW 


Th e Video Access Method (VAM) provides direct 
access from the primary application partition to 
the characters and character attributes of each 
frame. Its convenient interface provides the 
application system with independence from the 
position of the frame on the screen. In addi- 
tion, the application system can be independent 
of the model of workstation in use as long as 
only the basic video capability is used. (The 
basic, standard, and advanced video capabilities 
are described in the "Video Management" section.) 

VAM is a set of system common procedures. 


Forms -Oriented Interaction 

VAM is ideal for forms-oriented interaction; that 
is, interaction in which a form is displayed in a 
frame and the workstation operator enters data 
into the blank fields of the form. Direct cursor 
addressing and modification of individual 
characters and character attributes support this 
interaction . 

For example, the PutFrameAttrs operation is used 
to highlight the field to be entered next by 
setting reverse video for the range of character 
positions that compose the field. After the 
field is entered, the PutFrameAttrs operation is 
used again to reset the reverse video attribute 
on the character positions of the field. 


Advanced Text Processing 

VAM is also ideal for advanced text processing 
because it provides scrolling up and down of 
entire or partial frames. It is easy, for 
example, to scroll up the top four lines of a 
frame and insert a new line of text between the 
old fourth and fifth lines. During scrolling, 
character attributes scroll along with the text 
they affect. 
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OPERATIONS : PROCEDURES 

The Video Access 
listed below. 

PosFrameCursor 
PutFrameAttrs 

PutFrameChars 

QueryFrameChar 

ResetFrame 

ScrollFrame 


Method provides the operations 


establishes a visible cursor 
within the specified frame at 
the specified coordinates. 

establishes the same character 
attribute for a range of 
character positions within a 
specified frame. 

overwrites the specified 
character positions in the 
specified frame with the 
specified text string. 

returns a single character 
located in the character map at 
the specified coordinates of 
the specified frame. 

restores the frame to its 
initial state, that is, all 
character positions are blanked 
and all character attributes 
are reset. 

scrolls the specified portion 
of the specified frame up or 
down by the specified number of 
lines . 
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PosFrameCursor 


Description 

The PosFrameCursor procedure establishes a 
visible cursor within the specified frame at the 
specified coordinates. 

In a workstation with only basic video 
capability, PosFrameCursor erases any previously 
displayed cusor, even one in another frame. 

Procedural Interface 

PosFrameCursor (iFrame, iCol, iLine) : EroType 
where 

iFrame specifies the frame. 

iCol 

iLine specify the horizontal and vertical 

coordinates within iFrame at which 
to establish a cursor. To remove 
the cursor from a frame, both iCol 
and iLine must be specified as 255 
(OFFh) . 

Request Block 

PosFrameCursor is a system common procedure. 
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Put Fr ameAttr s 


Description 

The PutFrameAttrs procedure establishes the same 
character attribute for a range of character 
positions within a specified frame. The 

character attribute is applied first left to 
right and then top to bottom in the same manner 
as characters are moved into a frame. 

Procedural Interface 

PutFrameAttrs (iFrame, iCol, iLine, attr, 

nPos): ErcType 


where 




iFrame 

specifies the frame. 


iCol 

iLine 

specify the 
coordinates 

horizontal and 
within iFrame 

vertical 
at which 


to begin altering character 
attributes . 

attr the low-order 4 bits of attr specify 

the character attributes. For 

workstations with basic or standard 
video capabilities, the 

interpretation of the bits is as 
shown below. 

Bit Value Attribute 

0 1 Half-bright. (Note that 

if screen half-bright is 
set, the interpretation 
of the character attrib- 
ute half-bright is to 
negate half-bright (that 
is, to display the 
character at full 
brightness . ) 

1 2 Underlining. 
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Bit Value Attribute 

2 4 Reverse video. (Note 

that if screen reverse 
video is set, the inter- 
pretation of the charac- 
ter attribute reverse 
video is to negate re- 
verse video (that is, to 
display a light charac- 
ter on a dark back- 
ground . ) 

3 8 Blinking. 

For workstations with advanced video 
capability, attr is used as an index 
into the style RAM and sets/resets 
each attribute as established by the 
LoadStyleRam operation (see the 
"Video Display Manager" section) . 
(See the Workstation Hardware Manual 
for the interpretation of these bits 
for the specific model of 
workstation in use.) 

nPos specifies the number of character 

positions whose character attributes 
are to be changed . 

Request Block 

PutFrameAttrs is a system common procedure. 
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PutFr ameChar s 


Description 

The PutFrameChars procedure overwrites the 
specified character positions in the specified 
frame with the specified text string. PutFrame- 
Chars does not cause the character attributes 
associated with the character positions to change 
and never causes scrolling. 

Procedural Interface 

PutFrameChars (iFrame, iCol, iLine, pbText, 

cbText): ErcType 


where 




iFrame 

specifies the frame. 


iCol 

iLine 

specify the 
coordinates 

horizontal and 
within iFrame 

vertical 
at which 


the first character of the text 
string is to be moved. 

pbText 

cbText describe the text string to be moved 

into the character map. 

Request Block 

PutFrameChars is a system common procedure. 
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QueryFrameChar 

Description 

The QueryFrameChar procedure returns a single 

character located in the character map at the 

specified coordinates of the specified frame. 

Procedural Interface 

QueryFrameChar (iFrame, iCol, iLine, 

pbRet): ErcType 

where 

iFrame specifies the frame. 

iCol 

iLine specify the horizontal and vertical 

coordinates within iFrame of the 

character to be returned . 

pbRet is the memory address of the byte to 

which the character is to be 

returned . 

Request Block 

QueryFrameChar is a system common procedure. 
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Re set Frame 


Description 


The ResetFrame procedure restores the frame to 
its initial state, that is, all character 
positions are blanked and all character 
attributes are reset. The visible cursor of the 
frame is disabled (the iLineCursor and iColCursor 
fields of the frame descriptor of the Video 
Control Block are set to OFFh) . (The Video 
Control Block and frame descriptor are described 
in the "Video Management" section.) The 

coordinates at which the Sequential Access Method 
is to place the next character are set to the 
upper left corner of the frame (the frame 
descriptor fields iLineLeftOff and iColLeftOff 
are set to 0) . 

To support the Sequential Access Method's ability 
to request confirmation before scrolling 
information off the top of the frame, the first 
line of the frame is marked, unless pausing is 
disabled (the frame descriptor field iLinePause 
is set to 0, unless its previous value was OFFh). 

Procedural Interface 

ResetFrame (iFrame): ErcType 
where 

iFrame specifies the frame. 


Request Block 


ResetFrame is a system common procedure. 
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Sc roll Frame 


Description 


The ScrollFrame procedure scrolls the specified 
portion of the specified frame up or down by the 
specified number of lines. Vacated lines are 

replaced by blank lines. The portion to scroll 
begins at iLineStart and extends down to, but 

does not include, iLineMax. It is scrolled 
up/down by cLines and the bottommost/ topmost 
cLines lines of the scrolled area are filled with 
nulls (character code 0). fUp specifies the 

direction of the scroll. A value of OFFh for 

iLineStart or iLineMax specifies an imaginary 
line just below the bottom of the frame. 

For example, to scroll an entire frame up by one 
line, specify: 

iLineStart = 0 
iLineMax = OFFh 
cLines = 1 
fUp = TRUE 


To open a two-line space at line 4 (that is, 
lines 4 and 5 become blank) by scrolling the 
frame down, specify: 


iLineStart = 4 
iLineMax = OFFh 
cLines = 2 
fUp = FALSE 


To close the two-line space again, by scrolling 
the frame up (leaving the bottom two lines 
blank), specify: 


iLineStart = 4 
iLineMax = OFFh 
cLines = 2 
fUp = TRUE 


Video Access Method 
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Procedural Interface 


ScrollFrame (iFrame, iLineStart, iLineMax, 
cLines, fUp) : ErcType 

where 

iFrame specifies the frame. 

iLineStart is the line at the top of the area 
to scroll. 

iLineMax is the line just below the area to 

scroll . 

cLines is the number of lines by which to 

scroll . 

fUp specifies the direction of the 

scroll. It is TRUE for scroll up or 
FALSE for scroll down. 

Request Block 

ScrollFrame is a system common procedure. 
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26 KEYBOARD MANAGEMENT 


OVERVIEW 

The keyboard management facility enables the 
application system in the primary application 
partition to control the keyboard. 

Physical Keyboard 

The 98-key keyboard includes ten special function 
keys and eight keys with LEDs. The keyboard is 
unencoded , that is, pressing or releasing a key 
causes unambiguous information to be transmitted 
from the 8048 microprocessor in the keyboard to 
keyboard management. 

Consider this sequence: press the SHIFT key (to 
the left of the Z), press the A, release the A, 
release the SHIFT. An encoded keyboard would 
transmit only one item of information, the code 
for uppercase A. The Convergent unencoded 
keyboard, however, transmits four items of 
information, one for each key transition. It 
also differentiates the depression/release of the 
left SHIFT key from the depression/release of the 
right SHIFT key. 

Although this Manual refers to the keys by the 
standard symbols engraved on them, the meaning of 
each key is completely under the control of the 
application system in the primary application 
partition . 


Keyboard Modes : Unencoded and Character 

The application system in the primary application 
partition can request input from the keyboard in 
either of two modes: unencoded or character. 

In unencoded mode, the application system 
receives an indication of each key depression and 
release. This mode provides maximum 
flexibility. With unencoded mode, an application 
system can, for example, use any key as a SHIFT 
key, provide a hierarchy of SHIFT keys, and make 
decisions based on how long a key remains 
depressed. These are only three of many 
possibilities. The Editor makes extensive use of 
the flexibility afforded by unencoded mode. See 
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the Editor Manual and especially note the 
description of the MOVE and COPY keys in the 
"Manipulating the Selection" section. 

In character mode, the application system 
receives an 8-bit character code when a key other 
than SHIFT, CODE, LOCK, or ACTION is pressed. 
Character mode provides the application system 
with the same kind of information as a 
traditional n-key rollover encoded keyboard. 
However, even character mode provides greater 
flexibility than an encoded keyboard. As 

keyboard management converts the sequence of 
keyboard codes to 8-bit character codes, it 
accesses the Keyboard Encoding Table to direct 
its translation. 


Keyboard Encoding Table 

The Keyboard Encoding Table can be modified 
dynamically during application system execution, 
as well as at system build. This Table controls 
several aspects of the keyboard-code-to- 
character-code translation: 

o the character code to generate if the SHIFT 
key is/is not depressed, 

o whether the LOCK key has the effect of the 
SHIFT key for this key, 

o whether the key is Typematic (repeats), 

o the initial delay before beginning Typematic 
repeating, and 

o the frequency of Typematic repeating. 

The standard Keyboard Encoding Table (see 
Appendix B) provides an 8-bit superset of the 
ASCII printable characters. All 256 8-bit 
character codes can be generated from the 
keyboard. Each of the first 128 character codes 
(and some of the second 128) can be generated 
either by pressing a single key or by depressing 
the SHIFT key while depressing another key. 
Depressing the CODE key while depressing another 
key causes the high-order bit to be set ( 80h to 
be inclusive ORed) in the character code that 
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would otherwise be generated. Thus, the use of 
the CODE key (or the CODE and SHIFT keys) permits 
the generation of the remainder of the 256 
character codes. 

The ability to modify the Keyboard Encoding Table 
allows the keyboard to be customized without 
requiring the application system to support the 
complexity of directly interpreting the unencoded 
keyboard . 

A typical requirement is to use the numeric pad 
keys as function rather than data entry keys . 
This requires that the application system 
distinguish, for example, between the 3 on the 
numeric pad and the 3 on the typewriter pad. 
Changing the entry for the 3 on the numeric pad 
in the Keyboard Encoding Table provides the 
selected unique code to the application system 
whenever that key is pressed. (Support of this 
function may also require changing the key cap 
engraving for the numeric pad 3 key. ) 


LED Keys 


Seven of the eight keyboard LEDs are under 
control of the application system in the primary 
application partition. The LED in the LOCK key 
is under control of the application system 
control in unencoded mode and control of keyboard 
management in character mode. 


Submit Facility 


The System Input Manager augments keyboard 
management by providing a submit facility. The 
submit facility permits a sequence of characters 
from a file to be substituted for characters 
typed at the keyboard. The use of submit files 
allows the convenient repetition of command 
sequences. For example, a submit file might be 
used to run the sequence of programs necessary to 
produce end-of-month reports. 

One convenient way to use the submit facility is 
to use the Editor to prepare a submit file 
containing the same sequence of characters that 
would be typed to the desired programs. When 
this submit file is activated by a request from 
an application system or an Executive command, a 
character from the file is returned to the 
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application system whenever it requests a 
character from the keyboard. (Since the System 
Input Manager always operates in character mode, 
this is not applicable to an application system 
that uses the keyboard in unencoded mode.) 

Use of the submit facility does not preclude 
direct access to the keyboard. The application 
system can bypass an active submit file and read 
characters directly from the keyboard. This is 
necessary when the application system needs 
confirmation that a physical action was 
performed. For example, if a submit file is used 
to produce a sequence of reports, the application 
system needs to accept confirmation from the 
keyboard, rather than from the submit file, that 
the correct report forms are loaded into the 
printer . 

When requesting a character, an application 
system can specify that the character must come 
from the keyboard rather than the submit file. 
Also, a special sequence of characters (an escape 
sequence ) in the submit file can cause input to 
be accepted temporarily directly from the 
keyboard. Pressing a special key causes the 
input source to revert to the submit file. 

The System Input Manager has a complementary 
capability that records in a file all the 
characters typed at the keyboard, in addition to 
returning them to the application system 
requesting them. This file can be used as a 
record of all data typed at the workstation. 
Also, a file of this kind can be used as a submit 
file to repeat the same sequence of input 
characters to the same programs at a later time. 
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CONCEPTS 


Physical Keyboard 

The 98-key keyboard (see Figure 26-1) includes 
ten special function keys and eight keys with 
LEDs. The keyboard is unencoded , that is, 
pressing or releasing a key causes unambiguous 
information to be transmitted from the 8048 
microprocessor in the keyboard to keyboard 

management . 

When a key is depressed or released, the 8048 
microprocessor in the keyboard transmits a 

sequence of bytes to indicate all keys currently 
depressed. The seven low-order bits of each byte 
identify the key. The high-order bit is 0 in all 
bytes except the last of the sequence; it is set 
in the last byte to indicate the end of the 
sequence. A special code is transmitted to 
indicate that the last key was released and that 
no keys remain depressed. 

Keyboard management remembers which keys are 
depressed. When it receives a byte sequence from 
the keyboard microprocessor, it compares the keys 
now reported as depressed to the ones it 
remembers as depressed. The differences are the 
keys depressed/released. This information is 
represented in an 8-bit byte for each key 
depression/release. The seven low-order bits 
identify the key; the high-order bit is 0 to 
indicate key depression and 1 to indicate key 
release. 


Keyboard Modes: Unencoded and Character 

An application system in the primary application 
partition can use the SetKbdUnencodedMode 
operation to specify in which mode the ReadKbd 
and ReadKbdDirect operations are to function. 
There are two modes: unencoded and character. 

In unencoded mode, the application system 
receives an indication of each key depression and 
release. In this mode, the 8-bit byte, the 
keyboard code , returned by the ReadKbd or 
ReadKbdDirect operation identifies the key in the 
seven low-order bits; the high-order bit is 0 to 
indicate key depression and 1 to indicate key 
release. Appendix C specifies the 7-bit code 
generated for each key of the physical keyboard. 
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Display LED Function 

Pad Indicators Pad Keyboard Label Strip Cursor Pad 






















In character mode, the default mode, the 8-bit 
byte, the character code , returned by the ReadKbd 
or ReadKbdDirect operation signifies the 
depression of a key other than SHIFT, CODE, LOCK, 
or ACTION. Depression of SHIFT, CODE, and LOCK 
does not generate a character code, but 
influences the character codes generated for 
other keys depressed concurrently. ACTION has a 
special, system-wide meaning. (See the "ACTION 
Key" section below.) 


Type Ahead 


Keyboard management has a type-ahead buffer that 
stores character codes (or keyboard codes, if in 
unencoded mode) not yet read by an application 
system. If the workstation operator types too 
many characters in advance of processing, the 
excess are discarded. When the application 
system reads beyond those characters that were 
buffered successfully, it receives status code 
610 ("Type-ahead buffer overflow"). The size of 
the type-ahead buffer is usually 128 characters, 
but can be changed at system build. The content 
of the type-ahead buffer is discarded by the 
SetKbdUnencodedMode operation if the mode is 
actually changed and by the Chain and ErrorExit 
operations if the status code is abnormal 
(nonzero) (see the "Task Management" section). 


ACTION Key 


The ACTION key is a special kind of SHIFT key. 
It is processed specially, even in unencoded 
mode. The interpretation of all other keys is 
modified while ACTION is depressed. 

Key combinations that include the ACTION key are 
processed independently of calls by the 
application system to the ReadKbd or 
ReadKbdDirect operation and are not affected by 
character or keyboard codes stored in the type- 
ahead buffer. 

The key combination ACTION-FINISH terminates the 
execution of the current application system and 
invokes the Executive. The DisableActionFinish 
operation disables this feature. 
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The key combinations ACTION-A and ACTION-B invoke 
the Debugger if the Debugger is included in the 
Operating System at system build. 

Some of the key combinations that include the 
ACTION key are available for interpretation by an 
application system. Depressing CANCEL, HELP, 
0-9, or fl-flO while ACTION is depressed causes 
the keyboard code for the key depressed in 
conjunction with ACTION to be remembered. This 
code is an action code and can be obtained by 
calling the ReadActionCode operation. This 
allows the application system to test for special 
operator intervention without preventing type 
ahead. 

For example, the BASIC interpreter uses ACTION- 
CANCEL to interrupt computation without 
interfering with type ahead. 

If the workstation operator types a second key 
combination that includes the ACTION key before 
the first is read by the ReadActionCode 
operation, the second action code supersedes the 
first . 


Independence of Keyboard and Video 

Keyboard management never communicates with the 
video subsystem. The application system is free 
to interpret each character as it chooses and to 
echo characters to the video subsystem when and 
how it chooses. Keyboard management attaches no 
special significance to keys such as FINISH, 
HELP, RETURN, or DELETE. Only ACTION has special 
significance . 


Keyboard Encoding Table 

Keyboard management converts thg sequence of 
keyboard codes to 8-bit character codes using the 
Keyboard Encoding Table. (See Appendix B for the 
standard character set stored in the Keyboard 
Encoding Table.) The address of the the Keyboard 
Encoding Table is stored at address 270h in the 
System Common Address Table. This allows the 
Keyboard Encoding Table to be modified 
dynamically during application system execution. 
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as well as at system build. This Table controls 
several aspects of the keyboard-code-to- 
character-code translation: 

o the character code to generate if the SHIFT 
key is/is not depressed, 

o whether the LOCK key has the effect of the 
SHIFT key for this key, 

o whether the key is Typematic (repeats), 

o the initial delay before begining Typematic 
repeating, and 

o the frequency of Typematic repeating. 

See the section on "Building a Customized CTOS 
System Image" in the System Programmer 1 s Guide 
for detailed information on modifying the 
Keyboard Encoding Table. 


Standard Character Set 

The standard character set (see Appendix B) 
provides an 8-bit superset of the ASCII printable 
characters. All 256 8-bit character codes can be 
generated from the keyboard. Each of the first 
128 character codes (and some of the second 128) 
can be generated either by pressing a single key 
or by depressing the SHIFT key while depressing 
another key. Depressing the CODE key while 
depressing another key causes the high-order bit 
to be set (80h to be inclusive ORed) in the 
character code that would otherwise be 
generated. Thus, the use of the CODE key (or the 
CODE and SHIFT keys) permits the generation of 
the remainder of the 256 character codes. 


Submit Facility 


The submit facility permits a sequence of 
characters from a file to be substituted for 
characters typed at the keyboard. The use of 
submit files allows the convenient repetition of 
command sequences. 

A submit file can be activated by the 
SetSysInMode operation from an application system 
or by an Executive command. The submit file 
remains active until all its characters are read. 
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an end-of-file escape sequence is read from it, 
or the application system calls the SetSysInMode 
operation again . 

While a submit file is active, a character is 
read from the file and returned to the 
application system when the ReadKbd operation is 
called. After all characters are read from the 
submit file, it is automatically closed and 
subsequent ReadKbd operations read characters 
directly from the keyboard. The application 
system is not informed of the transition of input 
source from submit file to keyboard. This 
permits the use of submit files to be transparent 
to the application system. However, the 
QueryKbdState operation is available to an 
application system that needs to know whether a 
submit file is active. 

Two circumstances can temporarily disable a 
submit file: the SetKbdUnencodedMode operation 
and a read-direct escape sequence (see the "Read- 
Direct Escape Sequence" section below) . 

If the application system sets unencoded mode by 
calling the SetKbdUnencodedMode operation, then 
the ReadKbd operation reads keyboard codes from 
the keyboard, not from the submit file. Thus, 
the submit facility is not available to 
application systems that use the keyboard in 
unencoded mode. When the application system 
calls the SetKbdUnencodedMode operation with the 
argument FALSE to set character mode, the submit 
file is reactivated and characters are again read 
from the submit file. 

The submit file is also temporarily disabled when 
a read-direct escape sequence is read from the 
submit file. 

The ReadKbdDirect operation is available to read 
from the keyboard at all times, regardless of 
whether a submit file is active. 

The SetSysInMode operation can also specify 
recording mode. When recording mode is active, 
all characters typed at the keyboard and read in 
character mode by the ReadKbd operation (but not 
by the ReadKbdDirect operation) are written to a 
recording file , in addition to being returned to 
the application system of the ReadKbd 
operation. A recording file can later be used as 
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a submit file to repeat the same sequence of 
input characters. A recording file and a submit 
file cannot be active simultaneously. 


Submit File Escape Sequences 

Certain sequences of characters ( escape 
sequences ) invoke special functions when read 
from a submit file. A submit file escape 
sequence consists of two or three characters. 
The first is the character code 03h ( 40 / which 
indicates the presence of an escape sequence. 
The second character of the escape sequence is a 
code to identify the special function. The third 
character, if present, is an argument to the 
special function. The permitted codes are shown 
in Table 26-1 below. 


Table 26-1. Permitted Codes in Escape Sequences. 


Character Code Function 

$ 03h Two-character escape sequence 

that represents the character 
code 03h (40 • Since 03h is 
used to introduce escape 
sequences, this escape 
sequence (that is, two 
consecutive 40 is the only way 
to represent the 4 1 in a submit 
f ile . 


1 31h Three-character read-direct 

escape sequence (see below). 

2 32h End-of-file escape sequence. 

When this two-character escape 
sequence is read during a 
ReadKbd operation, the submit 
file is closed. The current 
and subsequent ReadKbd 
operations read characters 
directly from the keyboard. 
(This escape sequence is 
meaningful only in submit 
files that were created as 
recording files rather than 
through the Editor.) 
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Read-Direct Escape Sequence 


The read-direct escape sequence is a three- 
character submit file escape sequence that causes 
the ReadKbd operation to read characters directly 
from the keyboard until a specified key is 
depressed. The third byte of the escape sequence 
specifies the key that is to terminate input from 
the keyboard. When the specified key is 
depressed, its keyboard code is not returned to 
the application system. Rather, the current and 
all subsequent ReadKbd operations read characters 
from the submit file (unless another escape 
sequence redirects the input source). 

For example, it is frequently useful to have the 
operator enter data into a single field of an 
Executive command form (see the Executive Manual ) 
during the playing of a submit file . To 
accomplish this, the submit file should contain: 


data for the previous field 
OAh (RETURN/NEXT) 

the three-character escape sequence 03 h, 31 h, 
OAh ($, 1 , RETURN/NEXT) 

OAh (RETURN/NEXT) 

data for the next field 


When the escape sequence is read from the submit 
file, the cursor is blinking in the leftmost 
character position of the field that is to be 
entered manually. The operator then enters the 
desired data into the field and presses either 
the RETURN or the NEXT key (symbolized by 
RETURN/NEXT) . Pressing RETURN/NEXT resumes the 
execution of the submit file but control is not 
returned to the application system. The second 
RETURN/NEXT in the submit file ends the entry of 
data into the field and advances to the next 
field of the form. 
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As another example, it may be useful to have the 
operator enter data into all the fields of a form 
during the playing of a submit file. To 
accomplish this, include the four characters: 

03h , 31h, lBh , lBh 

in the submit file. This causes all characters 
except GO (lBh) to be read from the keyboard. 
When the operator completes the form and presses 
GO, the GO read from the keyboard resumes the 
playing of the submit file. The GO in the submit 
file (the lBh following the three-character 
escape sequence) completes the processing of the 
form. 


Application System Termination 

When an application system terminates (because of 
the Chain, Exit, or ErrorExit operations, or the 
ACTION-FINISH key combination): 

o if the keyboard was in unencoded mode, it is 
reset to character mode and the content of 
the type-ahead buffer is discarded, 

o the ACTION-FINISH feature is reenabled, and 

o the action code, if any, is discarded. 

In addition, if the application system terminates 
abnormally (because of the Chain or ErrorExit 
operations with a nonzero status code, or ACTION- 
FINISH) : 

o the content of the type-ahead buffer is 
discarded, and 

o the submit or recording file is closed. 

Termination of the application system does not 
affect the keyboard LEDs. However, the Executive 
resets the LEDs when it is called. 
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OPERATIONS : SERVICES 


Keyboard management provides the operations 

listed below. 

Beep activates an audio tone for 

one-half second. 

CheckpointSysIn writes the content of the 

current, partially filled, 
output buffer to the recording 
file if the System Input 
Manager is in recording mode. 

DisableActionFinish 

disables CTOS interpretation of 
ACTION-FINISH. 

QueryKbdLeds returns the status (on/off) of 

the eight keyboard LEDs. 

QueryKbdState returns the status of the 

keyboard and the System Input 
Manager to a structure provided 
by the application system. 

ReadActionCode returns the action code, if 

any, and resets the indication 
that an action code is 
available . 

ReadKbd reads one character from the 

keyboard, or from a submit file 
if one is active. 

ReadKbdDirect reads one character code (or 

keyboard code, if in unencoded 
mode) from the keyboard. 

SetKbdLed turns on/off one of the 

keyboard LEDs . 

SetKbdUnencodedMode 

selects unencoded or character 
mode . 

SetSysInMode changes the state of the System 

Input Manager. 


26-14 CTOS" Operating System Manual 



Beep 

Description 

The Beep service activates an audio tone for one- 
half second. 

Procedural Interface 

Beep: ErcType 

Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

52 
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CheckpointSysIn 

Description 


The CheckpointSysIn service writes the content of 
the current, partially filled, output buffer to 
the recording file if the System Input Manager is 
in recording mode. If the System Input Manager 
is in normal or submit mode, no action occurs. 

Procedural Interface 

CheckpointSysIn: ErcType 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

68 
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DisableActionFinish 


Description 


The DisableActionFinish service permits an 
application system in the primary application 
partition to disable CTOS interpretation of the 
ACTION-FINISH key combination. 

Normally, the operator can terminate the current 
primary application system by simultaneously 
depressing the ACTION and FINISH keys. However, 
it is highly undesirable to terminate the 
execution of certain types of application 
systems. DisableActionFinish permits such 

application systems to disable CTOS 
interpretation of ACTION-FINISH. 

Procedural Interface 

DisableActionFinish (fDisable): ErcType 
where 

fDisable disables ACTION-FINISH if TRUE or 

enables ACTION-FINISH if FALSE. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

67 

12 

fDisable 

2 
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QueryKbdLeds 

Description 


The QueryKbdLeds service returns the state 
(on/off) of the eight keyboard LEDs. 

Procedural Interface 


QueryKbdLeds: (pLEDsRet) : ErcType 


where 


Request Block 


pLEDsRet 

is the memory 

address of a byte to 


which the state 

s is returned. 


Bit 

Key 


0 (low) 

flO 


1 

f 9 


2 

f 8 


3 

f 3 


4 

f 2 


5 

fl 


6 

LOCK 


7 

OVERTYPE 


sLEDs Ret 

is always 1. 





Size 


Offset 

Field 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

55 

12 

reserved 

6 


18 

pLEDsRet 

4 


22 

sLEDsRet 

2 

1 
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QueryKbdState 

Description 


The QueryKbdState service returns the status of 
the keyboard and the System Input Manager to a 
structure provided by the application system in 
the primary application partition. 

Procedural Interface 

QueryKbdState (pKbdDescRet ) : ErcType 

where 

pKbdDescRet is the memory address of a 16-byte 
keyboard descriptor area to which 
the status of the keyboard and the 
System Input Manager are returned. 


Size 

Offset Field (bytes ) 


0 fUnencodedMode 1 

1 sysInMode 1 

2 fhSysIn 2 

4 reserved 12 


where 

fUnencodedMode 

is character mode if FALSE or 
unencoded mode if TRUE. 

sysInMode 

0 = normal mode (neither submit 

nor recording mode is active) ; 

1 = recording mode (a copy of 

keyboard input is being 
written to the file specified 
by fhSysIn) ; 

2 = submit mode (input is being 

read from the file specified 
by fhSysIn); 

3 = escaped submit mode (the 

submit file specified by 
fhSysIn is in use, but a read- 
direct escape sequence was 
read from that file causing 
input to be read directly from 
the keyboard until a special 
key is pressed) . 
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fhSysIn 

is the file handle of the 
currently open submit or recording 
file. If sysInMode is 0 (normal 
mode), fhSysIn is not meaningful. 


Request Block 


sKbdDescRet is always 16. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

58 

12 

reserved 

6 


18 

pKbdDescRet 

4 


22 

sKbdDescRet 

2 

16 
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Re adAc t ionCode 


Description 


The ReadActionCode service returns the action 
code, if any, and resets the indication that an 
action code is available. If no action code is 
available, ReadActionCode returns status code 609 
("No action code available"). 

Procedural Interface 

ReadActionCode (pCodeRet) : ErcRet 
where 

pCodeRet is the memory address of a byte to 

which the keyboard code of the key 
that was depressed while the ACTION 
key was depressed is to be returned. 

Request Block 


sCodeRet is always 1. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

60 

12 

reserved 

6 


18 

pCodeRet 

4 


22 

sCodeRet 

2 

1 
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ReadKbd 


Description 


The ReadKbd service reads one character from the 
keyboard. If a submit file is currently active, 
ReadKbd reads the character from that file 
instead of from the keyboard. 

Procedural Interface 

ReadKbd (pCharRet) : ErcType 

where 

pCharRet is the memory address of a byte to 

which the character is to be 
returned . 


Request Block 


sCharRet is always 1. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchl^esp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

53 

12 

reserved 

6 


18 

pCharRet 

4 


22 

sCharRet 

2 

1 
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ReadKbdDirect 


Description 


The ReadKbdDirect service reads one character 
code (or keyboard code, if in unencoded mode) 
from the keyboard. ReadKbdDirect never reads 

from a submit file. Special modes permit testing 
for the presence of a character in the type-ahead 
buffer . 

Procedural Interface 

ReadKbdDirect (mode, pCharRet) : ErcType 
where 

mode is one of the following codes: 

Code Description 

0 wait until a character 

code (or keyboard code, if 
in unencoded mode) is 

available, then return it. 

1 if a character code (or 

keyboard code, if in 

unencoded mode) is 

currently available, 

return it. If no 

character code or keyboard 
code is available, return 
status code 602 ("No 
character available"). 

2 wait until a character 

code (or keyboard code, if 
in unencoded mode) is 

available, then return a 
copy of it but do not 

remove it from the type- 
ahead buffer. A 

subsequent ReadKbdDirect 
or ReadKbd operation reads 
the same character code or 
keyboard code again. 
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Code 


Description 


3 if a character code (or 
keyboard code, if in 
unencoded mode) is 

available, return a copy 
of it but do not remove it 
from the type-ahead 
buffer. If no character 
code or keyboard code is 
available, return status 
code 602 ("No character 
available" ) . 

pCharRet is the memory address of a byte to 

which to return a character code or 
keyboard code . 

Request Block 

sCharRet is always 1. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

54 

12 

mode 

2 


14 

reserved 

4 


18 

pCharRet 

4 


22 

sCharRet 

2 

1 
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SetKbdLed 


Description 


The SetKbdLed service turns one of the keyboard 
LEDs on or off. 

Procedural Interface 

SetKbdLed (iLED, fOn) : ErcType 

where 

iLED is the identification of the LED to 

turn on/off. 

iLED Key 

0 flO 

1 f 9 

2 f 8 

3 f 3 

4 f 2 

5 fl 

6 LOCK (only if the keyboard 

is in unencoded 
mode ) 

7 OVERTYPE 

fOn is on if TRUE or off if FALSE. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

56 

12 

iLED 

2 


14 

fOn 

2 
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SetKbdUnencodedMode 


Description 


The SetKbdUnencodedMode service selects unencoded 
or character mode. SetKbdUnencodedMode discards 
the content of the type-ahead buffer if the mode 
is actually changed. 

Procedural Interface 

SetKbdUnencodedMode (fOn): ErcType 

where 

fOn is unencoded mode if TRUE or 

character mode if FALSE. 


Request Block 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

57 

12 

fOn 

2 
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Se tSys InMode 
Description 


The SetSysInMode service changes the state of the 
System Input Manager. SetSysInMode first closes 
the existing submit or recording file, if any, 
and then sets the specified mode using the 
specified file, if any. 

Procedural Interface 

SetSysInMode (iMode, fhSysIn) : ErcType 
where 

iMode is one of the foilwing codes: 

Code Mode 

0 normal mode (neither sub- 
mit nor recording mode is 
active ) ; 

1 recording mode (a copy of 

keyboard input is to be 
written to the file 

specified by fhSysIn) ,* 

2 submit mode (input is to 
be read from the file 
specified by fhSysIn) . 

fhSysIn is the file handle of the open file 

to use for the submit or recording 
file. The application system must 
make no further reference to this 
file. This is not used if iMode is 
0 (normal mode) . 
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Request Block 
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27 COMMUNICATIONS MANAGEMENT 


OVERVIEW 

Each workstation, except an AWS-210 workstation, 
includes an integral serial input/output (SIO) 
communications controller that supports two 
communications channels. Each channel can be 
used in asynchronous, character-synchronous, or 
bit-synchronous mode. Software support is 
provided at three levels: 

o Terminal Emulator, 

o Sequential Access Method, and 

o user-written Communication Interrupt Service 
Routine . 

The Asynchronous Terminal Emulator (ATE), the 
X.25 Terminal Emulator, the 3270 Terminal 
Emulator, and the 2780/3780 RJE Terminal Emulator 
provide the ability to communicate with remote 
computers without requiring any user 
programming. See the Asynchronous Terminal 
Emulator Manual , the X.25 Network Gateway Manual , 
the 3270 Terminal Emulator Manual , and the 
2780/3780 RJE Terminal Emulator Manual . 

The Sequential Access Method supports full- 
duplex, asynchronous transmission, and X.25 
transmission. See the "Sequential Access Method" 
section . 

More specialized communications needs require a 
user-written Communication Interrupt Service 
Routine. See the "Interrupt Handlers" section 
and the System Programmer ’ s Guide . 
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OPERATIONS ; PROCEDURES 

Communications management provides the operations 
listed below. 

Lockln inputs from the SIO 

communications controller. 

Lockout outputs from the SIO 

communications controller. 
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Lockln 


Description 

The Lockln procedure must be used in an IWS 
workstation to input from the SIO communications 
controller. Lockln is necessary because the SIO 
communications controller supports two 

communications channels. 

If Lockln is not used, there may be unpredictable 
results on both the input/output operation being 
attempted, and the DMA operation in progress on 
the other Channel . In a cluster configuration, 
this almost certainly results in a system crash 
at the workstation in question, and possibly 
severe performance degradation throughout the 
cluster configuration. 

Procedural Interface 

Lockln (bPort, bValueRet) 

where 

bPort is the input/output port from which 

a byte value is to be read. 

bValueRet is the byte value read. 

Request Block 

Lockln is an object module procedure. 
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Lockout 


Description 

The Lockout procedure must be used in an IWS 
workstation to output from the SIO communications 
controller. Lockout is necessary because the SIO 
communications controller supports two 

communications channels. 

If Lockout is not used, there may be 

unpredictable results on both the input/output 
operation being attempted, and the DMA operation 
in progress on the other Channel. In a cluster 
configuration, this almost certainly results in a 
system crash at the workstation in question, and 
possibly severe performance degradation 
throughout the cluster configuration. 

Procedural Interface 

Lockout (bPort, bValue) 

where 

bPort is the input/output port to which a 

byte value is to be written. 

bValue is the byte value to be written. 

Request Block 


Lockout is. an object module procedure. 
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28 TIMER MANAGEMENT 


OVERVIEW 
Real-Time Clock 


Each workstation has a Real-Time Clock ( RTC ) . 
The RTC of the IWS family of workstations uses 
the power-line frequency (50 or 60 Hz) as a 
timing source. The RTC of the AWS family of 

workstations uses a crystal-controlled timing 
source. 

Timer management uses the RTC to provide both the 
current date and time of day and the timing of 
intervals (in units of 100 ms). (For a cluster 
workstation without a local file system, the 
current date and time is maintained at the master 
workstation. For a cluster workstation with a 
local file system, the current date and time is 
maintained at both the master and cluster 
workstations . ) 

A client process can request that a message be 
sent to a specified exchange either once after a 
specified interval or repetitively with a 
specified constant interval between send 

operations. The first time a message is sent to 
an exchange can be up to 100 ms earlier than 
specified. Subsequent intervals are timed 

exactly. 


Programmable Interval Timer 

The workstations in the IWS family also have a 
second timer, a Programmabl e Interval Timer 
(PIT), that uses a 19.5 kHz crystal -con trolled 
timing source to provide a resolution of 51.3 
microseconds. The PIT is controlled by a 16-bit 
counter and therefore has a maximum interval of 
approximately three seconds. 

Timer management uses the PIT to provide high- 
resolution, low-overhead activation of user 
pseudointerrupt handlers. A client process or 
interrupt handler can request that "a pseudo- 
interrupt handler be activated after a specified 
interval. Pseudointerrupt handlers are not 
available on the AWS workstation. 
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CONCEPTS 


Convergent Date/Time Format 

The Convergent date/time format provides a 
compact representation of the date and the time 
of day that precludes invalid dates and allows 
simple subtraction to compute the interval 
between two dates. The Convergent date/ time 
structure is shown in Table 23-1 below. 

The date/time format is represented in 32 bits to 
an accuracy of one second. The high-order 15 
bits of the high-order word contain the count of 
days since March 1, 1952. The use of a 15-bit 
field allows dates up to the year 2042 to be 
represented. The low-order bit of the high-order 
word is 0 to represent AM and 1 to represent 
PM. The low-order word contains the count of 
seconds since midnight/noon. Valid values are 0 
to 43199. 

The current date/time is maintained in the master 
workstation (for all the workstations of a 
cluster configuration) or in the standalone 
workstation. It can be accessed by the 
GetDateTime operation and modified by the 
SetDateTime operation. 



Table 28-1. 

Convergent Date/Time Structure. 

Offset 

Field 

Size 
(bytes ) 

Description 

2 

seconds 

2 

Count (0-43199) of 
seconds since last 
midnight/noon . 

4 

dayTimes2 

2 

Count (0-65535) of 
12-hour periods 

since March 1, 1952 
(0 = null 
date/time) . 
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System Date/Time Format 


If a client process executing on a master or 
standalone workstation needs to know the time to 
greater precision than one second, it can access 
the system date/time structure, the address of 
which is at address 240h in the System Common 
Address Table (described in Appendix E) . The 
format of the system date/time structure is shown 
in Table 28-2 below. 



Table 28-2. 

System Date/Time Structure. 

Offset 

Field 

Size 

(bytes) 

Description 

0 

ticks 

1 

Counted down from 5 
(50 Hz) or 6 (60 
Hz) to 0. 

1 

hundredMsec 1 

Count (0-9) of 100 
ms since last 
second . 

2 

seconds 

2 

Count (0-43199) of 
seconds since last 
midnight/ noon . 

4 

dayTimes2 

2 

Count (0-65535) of 
12-hour periods 
since March 1, 1952 
(0 = null 
date/time) . 


Expanded Date/Time Format 

The ExpandDateTime and CompactDateTime operations 
convert between Convergent date/time format and 
an expanded date/time format in which year, 
month, day of month, etc., are represented as 
discrete fields. The expanded date/time format 
is shown in Table 28-3 below. 
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Table 28-3. Expanded Date/Time Format. 


Offset 

Field 

Size 

(bytes) 

Description 

0 

year 

2 

1952-2042 (0 = null 
date/time) 

2 

month 

1 

0 = Jan, 11 = Dec 

3 

day of 

month 1 

1-31 

4 

day of 

week 1 

0 = Sun, 6 = Sat 

5 

hour 

1 

0-23 

6 

minute 

1 

0-59 

7 

second 

1 

0-59 


Timer Management Operations 

There are five classes of timer management 
operations: date/time, format conversion, delay, 
Real-Time Clock, and Programmable Interval Timer. 


Date/Time 

The GetDateTime and SetDateTime operations access 
and modify the current CTOS date/time. 


Format Conversion 

The ExpandDateTime and CompactDateTime operations 
convert between Convergent date/time format and 
an expanded date/time format in which year, 
month, day of month, etc., are represented as 
discrete fields. See Table 28-3 above. 


Delay 


The Delay operation allows a process to suspend 
execution for a specified interval (in units of 
100 ms ) . 
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Real-Time Clock 


The OpenRTClock operation initiates the use of a 
data structure provided by a client process for 
control of complex Real-Time Clock ( RTC ) 
services. This data structure, the Timer Request 
Block (TRB) , is shared by the client process and 
timer management. The CloseRTClock operation 
terminates the sharing of the TRB. 

The TRB defines the interval after which a 
message is sent to a specified exchange. The 
message can be sent either once after the 
specified interval or repetitively with the 
specified constant interval between send 
operations. The message is the TRB itself. 

The client process must acknowledge receipt of 
the TRB (as described below) before timer 
management will send the same TRB again. This 
ensures that system resources (link blocks) are 
not consumed by queueing the same TRB at the same 
exchange many times. The client process can also 
dynamically modify other fields of the TRB. 

The format of a TRB is shown in Table 28-4 below. 


Timer Management Operation. Every 100 ms, the 
timer management RTC interrupt handler performs 
the following sequence of operations on each 
active TRB. This sequence ensures that timer 
management will not send the same TRB again until 
the client process decrements the cEvents field 
to 0 . 

1. If the counter field is 0, do nothing. 

2. Decrement the counter field by 1. 

3. If the counter field has not become 0, .do 
nothing more. 

4. If the cEvents field is 0, send a message to 
the exchange specified by the exchResp 
field. The message is the TRB itself (not a 
copy of the TRB) . 

5. Increment the cEvents field by 1. 

6. Copy the counterReload field to the counter 
field . 
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Table 28-4. Timer Request Block Format. 


Offset 

Field 

Size 
(bytes ) 

Description 

0 

counter 

2 

Decremented every 
100 ms. 

2 

counterReload 2 

Copied to counter 
field when counter 
reaches 0. 

4 

cEvents 

2 

Incremented when 
counter field 
reaches 0 . 

6 

exchResp 

2 

Response exchange . 

8 

ercRet 

2 

Status code. Not 
used by timer 
management. Avail- 
able for the client 
process . 

10 

rqCode 

2 

Request code. Not 
used by timer 
management. The 
client process 
should place a 
unique value in 
this field so that 
it can identify its 
TRB when it is 
received as a 
message . 


"One-Shot" Timing. A client process should use 
the sequence below to initialize a TRB to time a 
single interval (a "one-shot" timer). 

1. Set the counter field to 0. 

2. Call the OpenRTClock operation. 

3. Set the cEvents field to 0. 
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4. Set the counterReload field to 0. 

5. Set the counter field to the desired 

interval . 

Use the Wait or Check operation (specifying the 
exchange specified by the exchResp field) to 

receive the indication that the interval 

expired. (The Wait and Check operations are 
described in the 11 Interprocess Communication 
Management" section.) Remember that the RTC only 
operates in units of 100 ms. Thus, if the 

counter field is set to 3, the TRB can be sent to 
the exchResp exchange in as few as 200 ms or as 
many as 300 ms. To reuse the TRB to time another 
single interval, repeat the sequence above from 
step 3 . 


Repetitive Timing. A client process should use 
the sequence below to initialize a TRB for 
repetitive timing. 

1. Set the counter field to 0. 

2. Call the OpenRTClock operation. 

3. Set the cEvents field to 0. 

4. Set the counterReload field to the desired 
interval . 

5. Set the counter field to the desired 
interval . 

The first time that the TRB is sent to the 
exchResp exchange can be up to 100 ms earlier 
than specified. Subsequent intervals are timed 
exactly. Exact timing is guaranteed because the 
counter field of the TRB is decremented even if 
the client process has not finished processing 
the previous event. The cEvents field provides a 
continuous count of the events that have occurred 
but are not yet processed. If the client process 
is too slow, the count in the cEvents field 
becomes ever larger. Under these circumstances, 
the count in the cEvents field provides a measure 
of how far behind processing has fallen. 

The client process should use the sequence below 
to process the TRB. This sequence avoids a race 
condition and yet processes the correct number of 
events . 
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1. Receive indication that the interval expired 
by using either the Wait or Check operation 
and specifying the exchange specified by the 
exchResp field. 

2. If the cEvents field is 0, processing is 

complete; return to step 1. (In this 

sequence, it is possible to receive a TRB in 
which cEvents is 0; thus it is necessary to 
perform this test before processing the 
event . ) 

3. Process the event. Processing is 

application-specific . 

4. Decrement the cEvents field by 1 . (It is not 
necessary to decrement the cEvents field in a 
single instruction unless the client process 
is keeping a count of events.) 

5. Repeat the processing sequence from step 2. 


Programmable Interval Timer 

The Programmable Interval Timer (PIT), which is 
present in IWS workstations^ is accessed through 
the SetTimerlnt and ResetTimerlnt operations. 

The SetTimerlnt operation establishes a pseudo- 
interrupt handler in the application system to 
receive a ' pseudointerrupt after a specified 
interval (in units of 51.3 microseconds). The 
SetTimerlnt operation specifies the memory 
address of a Timer Pseudointerrupt Block (TPIB) 
in user memory that must be allocated by the 
application system. 

The format of a Timer Pseudointerrupt Block is 
shown in Table 28-5 below. 

It is sometimes convenient to have a single 
pseudointerrupt handler service the 
pseudointerrupts associated with multiple 
TPIBs . To do this, the pRqBlkRet field of each 
TPIB must point to the same 4-byte memory area 
and the SetTimerlnt operation must be invoked for 
each TPIB. The pseudointerrupt handler must 
examine this 4-byte memory area to determine 
which TPIB caused activation of the pseudo- 
interrupt handler. Even when the pseudointerrupt 
handler is serving only a single TPIB, pRqBlkRet 
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must still point to an otherwise unused 4-byte 
memory area. 

The ResetTimerlnt operation terminates a previous 
SetTimerlnt operation. 

To understand the operation of a pseudointerrupt 
handler, read the "Interrupt Handlers" section. 



Table 28-5. 

Timer Pseudointerrupt Block. 

Offset 

Field 

Size 
(bytes ) 

Description 

0 

linkFieldl 

4 

Used by the OS. 

4 

linkField2 

4 

Used by the OS. 

8 

plntHandler 4 

CS:IP of the entry 
point of the 
pseudointerrupt 
handler . 

12 

saData 

2 

Segment base ad- 
dress of the data 
segment to be used 
by the pseudo- 
interrupt handler. 

14 

clntervals 

2 

Interval before the 
pseudointerrupt is 
to occur (in units 
of 51.3 micro- 
seconds ) . 

16 

pRqBlkRet 

4 

The memory address 
of 4 bytes into 
which the memory 
address of the TPIB 
is returned when 
the pseudointerrupt 
handler is invoked. 

20 

footprint 

2 

Used by the OS. 

22 

delta 

2 

Used by the OS. 

24 

reserved 

8 

Used by the OS. 
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OPERATIONS: PRIMITIVES, PROCEDURES, AND SERVICES 


Timer management operations are categorized by 
function in Table 28-6 below. 



Date/Time 

GetDateTime 


SetDateTime 
Format Conversion 

Compact Da teTime 


ExpandDateTime 


Delay 

Delay 


Real-Time Clock 

CloseRTClock terminates the use of the 

specified TRB. 
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returns the current data/time 
in Convergent date/time format. 

sets the date/time of the OS. 


converts from expanded 
date/time format to Convergent 
date/time format. 

converts from Convergent 
date/time format to expanded 
date/time format. 


delays the execution of the 
client process for the 
specified interval. 




Ope nRTC lock establishes a TRB between 

the client process and timer 
management . 

Programmable Interval Timer 

ResetTimerlnt terminates the TPIB 

initiated by a SetTimerlnt 
call . 

SetTimerlnt establishes a PIT pseudo- 

interrrupt handler. 
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CloseRTClock 

Description 

The CloseRTClock service terminates the use of 
the specified TRB. 

The format of a TRB is shown in Table 28-4 above. 

Procedural Interface 

CloseRTClock (pRqTime) : ErcType 

where 

pRqTime 

sRqTime describe a TRB that is currently 

open . 

Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

50 

12 

reserved 

6 


18 

pRqTime 

4 


22 

sRqTime 

2 
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CompactDateTime 

Description 


The CompactDateTime procedure converts from 
expanded date/time format to Convergent date/time 
format. Each field of the expanded date/time 
format is verified. If the day of week does not 
agree with the other fields, status code 2702 
("Day and date disagree") is returned. 

The expanded date/time format is shown in Table 
28-3 above. 

Procedural Interface 

CompactDateTime (pExpDateTime, 

pDateTimeRet ) : ErcType 

where 

pExpDateTime 

is the memory address of an 8-byte 
expanded date/time block. 

pDateTimeRet 

is the memory address of 4 bytes to 
which the Convergent date/time 
format is to be returned. 

Request Block 

CompactDateTime is an object module procedure. 
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Delay 

Description 


The Delay procedure delays the execution of the 
client process for the specified interval. 

Procedural Interface 

Delay (n): ErcType 

where 

n is the interval to delay (in units 

of 100 ms) . 


Request Block 


Delay is a system common procedure. 
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ExpandDateTime 

Description 

The ExpandDateTime procedure converts from 
Convergent date/time format to an expanded 
date/ time format in which year, month, day of 
month, etc., are represented as discrete fields. 

The expanded date/ time format is shown in Table 
28-3 above. 

Procedural Interface 

ExpandDateTime (dateTime, 

pExpDateTimeRet ) : ErcType 

where 

dateTime is the 32-bit date/time in 

Convergent format. 

pExpDateTimeRet 

is the memory address of an 8-byte 
expanded date/time block to which 
expanded date/time format is to be 
returned . 


Request Block 


ExpandDateTime is an object module procedure. 
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GetDateTime 


Description 

The GetDateTime service returns the current 
date/time in the Convergent date/time format. 

Status code 46 ("Master workstation going down") 
is returned if a DisableCluster operation was 
performed. (See the "Cluster Management" 

section.) If status code 46 ("Master workstation 
going down") is returned, the low-order word of 
the structure pointed to by pDateTimeRet contains 
the time (in seconds) remaining before the master 
workstation goes down. 

Procedural Interface 

GetDateTime (pDateTimeRet): ErcType 
where 

pDateTimeRet 

is the memory address of the 4-word 
structure to which the date/time is 
returned . 

Request Block 

sDateTimeRet is always 4. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

1 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

14 

12 

reserved 

6 


18 

pDateTimeRet 

4 


22 

sDateTimeRet 

2 

4 
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OpenRTClock 

Description 


The OpenRTClock service establishes a TRB between 
the client process that requests the timing 

services and timer management. The client 

process and timer management communicate by- 

changing the fields in the TRB after an 
OpenRTClock call. 

The format of a TRB is shown in Table 28-4 above. 
Procedural Interface 

OpenRTClock (pRqTime) : ErcType 
where 

pRqTime is the memory address of the client- 

process-provided TRB to be shared by 
the client process and timer 

management . 

Request Block 

sRqTime is always 12. 


Offset 

Field 

Size 
(bytes ) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

49 

12 

reserved 

6 


18 

pRqTime 

4 


22 

sRqTime 

2 

12 
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ResetTimerlnt 


Description 


The ResetTimerlnt primitive terminates the TPIB 
initiated by a previous SetTimerlnt call. 
ResetTimerlnt is used only to cancel a previous 
SetTimerlnt operation before the requested 
pseudointerrupt has occurred. The "No such TPIB" 
status code is returned if the pseudointerrupt 
has already occurred. 

The format of a TPIB is shown in Table 28-5 
above . 

Procedural Interface 

ResetTimerlnt (pTPIB) : ErcType 

where 

pTPIB is the memory address of the TPIB to 

be terminated. 


Request Block 


ResetTimerlnt is a Kernel primitive. 
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SetDateTime 


Description 

The SetDateTime service sets the date/time of the 
OS. 


Procedural Interface 


Request Block 


SetDateTime 

where 

seconds 

dayTimes2 


(seconds, dayTimes.2) : ErcType 


is the count (0-43199) of seconds 
since the last midnight /noon . 

is the count ( >-6 553 5 ) of 12-hour 
periods since March 1, 1952. 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

4 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

51 

12 

seconds 

2 


14 

dayTimes2 

2 
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SetTimerlnt 


Description 

The SetTimerlnt primitive establishes a PIT 
pseudointerrupt handler and specifies the 
interval after which the PIT pseudointerrupt is 
to be generated. SetTimerlnt can be called from 
a PIT pseudointerrupt handler to reestablish the 
PIT pseudointerrupt handler with a (possibly 
different) interval. Multiple pseudointerrupt 
handlers can use the PIT simultaneously. 

The format of a TPIB is shown in Table 28-5 
above . 

Procedural Interface 

SetTimerlnt (pTPIB) : ErcType 
where 

pTPIB is the memory address of the TPIB. 

Request Block 

SetTimerlnt is a Kernel primitive. 
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29 INTERRUPT HANDLERS 


OVERVIEW 


An interrupt is an event that interrupts the 
sequential execution of processor instructions . 
When an interrupt occurs, the current hardware 
context (the state of the hardware registers) is 
saved. This context save is performed partly by 
the 8086 processor and partly by the Operating 
System. After the condition causing the 

interrupt is identified and acted upon, the 
context of the interrupted process (or another 
higher priority process) is restored and 
execution resumed as if the interrupt never 
occurred. 

(The description that follows is not applicable 
to AWS workstations, since AWS workstations do 
not contain Multibus slots or support user- 
written interrupt handlers.) 


External Interrupts 

External (true) interrupts are caused by 
conditions that are external to the 8086 
processor and are asynchronous to the execution 
of processor instructions. 

In a standard workstation, eight of the interrupt 
levels are ordered in priority and controlled by 
the 8259A Programmable Interrupt Controller 
(PIC). They can be masked (ignored) by the use 
of the processor interrupt-enable flag. They can 
also be selectively masked (that is, some 
recognized, some ignored) by programming the 
8259A PIC. 

Four of these eight interrupt levels are used for 
the standard device controllers of a work- 
station. The other four interrupt levels are 
available for the connection of device 
controllers that are installed in the Multibus- 
compatible card slots. 

One interrupt level (with a higher priority than 
those controlled by the 8259A PIC) supports the 
critical error conditions: 

o write-protect violation. 
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o nonexistent memory or device address 
reference, 

o memory parity error, and 

o power failure detection. 


Internal Interrupts 

Internal interrupts (traps) are caused by and are 
synchronous with the execution of processor 
instructions. The causes of internal interrupts 


are 

: 




o 

an erroneous divide 

instruction. 

o 

the 

8086 

Trap Flag, 


o 

the 

and 

INTO 

( interrupt 

on overflow) instruction 

o 

the 

I NT 

( interrupt ) 

instruction . 


Device Handlers 


Accommodation of user— written device handlers was 
a major design goal of the CTOS Operating 
System. A device handler can be part of either 
an application system or a system service 
process. Its interrupt handler can let the 
Kernel save the process context (in which case it 
can be written in FORTRAN or Pascal), or it can 
receive the interrupt directly from the 
hardware. Interprocess communication provides an 
efficient, yet formal, interface from interrupt 
handler to device handler and from device handler 
to application system. 

Read the section on interrupts and the 8259A PIC 
in the Workstation Hardware Manual before 
attempting to write an interrupt handler. 
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CONCEPTS 


An interrupt is an event that interrupts the 
sequential execution of processor instructions. 
When an interrupt occurs, the current hardware 
context (the state of the hardware registers) is 
saved. This context save is performed partly by 
the 8086 processor and partly by the Operating 
System. 

After the condition causing the interrupt is 
identified and acted upon, the CTOS Kernel either 
(1) restores the context of the interrupted 
process and resumes its execution, or (2) 
determines that a higher priority process is 
ready to execute, performs a context switch, and 
initiates execution of the higher priority 
process. 

Interrupts can be nested, that is, a higher 
priority interrupt can interrupt the execution of 
an interrupt handler that is servicing a lower 
priority interrupt. When the higher priority 
interrupt handler completes its processing, 
execution of the lower priority interrupt handler 
resumes . 


Interrupt Types 


The 8086 processor has a simple yet versatile 
interrupt system. Each potential source of 
interrupt is assigned an interrupt type code. 
This is a number in the range 0-119 and is used 
to vector (direct) the interrupt to the 
appropriate interrupt handler. The Interrupt 
Vector Table begins at physical memory address 0 
and contains a 4-byte entry for each interrupt 
type. Each 4-byte entry contains the logical 
memory address (CSsIP) of the first instruction 
to be executed when an interrupt of that type 
occurs . 

The interrupt types are shown in Table 29-1 
below. 
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Table 29-1. Interrupt Types. (Page 1 of 2) 


Interrupt 

Type 

Code 

8259A 

PIC 

Level 

Description 

Interrupt 

Vector 

Address 

0 


Divide error trap. 

OOh 

1 


Single step trap 
(used by the 
Debugger) . 

04h 

2 


Nonmaskable external 08h 

interrupts (write- 
protect violation, 
nonexistent memory or 
device address refer- 
ence, memory parity 
error, or power 
failure detection. 

3 


Breakpoint trap OCh 

(used by the Debugger) . 

4 


Signed arithmetic 
overflow trap. 

lOh 

5 


Access to Kernel 
primitives . 

14h 

6 


Access to system 
services . 

18h 

7 


Access to system 
common procedures. 

ICh 

8 

0 

Multibus devices. 

2 Oh 

9 

1 

SIO communications 
controller . 

24h 

10 

2 

Multibus devices. 

28h 

11 

3 

Programmable 
Interval Timer. 

2Ch 
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Table 29-1. 

Interrupt Types. (Page 2 of 2) 


Interrupt 

8259A 


Interrupt 

Type 

PIC 


Vector 

Code 

Level 

Description 

Address 

12 

4 

Printer, keyboard, 
Real-Time Clock, and 
high-speed mathe- 
matics coprocessor. 

3 Oh 

13 

5 

Multibus devices. 

34h 

14 

6 

Multibus devices. 

38h 

15 

7 

Disk storage sub- 
system (floppy and 
Winchester) . 

3Ch 

16-119 


Available for 
software-generated 
interrupts and 
Multibus device 
interrupts using 
cascaded slave 
8259A PICs on Multi- 
bus logic boards. 

40h-lDCh 


Interrupts 


Interrupts are either external or internal . 


External Interrupts 

External interrupts are caused by conditions that 
are external to the 8086 processor and are 
asynchronous to the execution of processor 
instructions. There are two kinds of external 
interrupts: maskable and nonmaskable. 


Maskable Interrupts. Maskable interrupts are 
given a priority and controlled by the 8259A 
Programmable Interrupt Controller (PIC) . They 
can be masked ( ignored! by the use of the 
processor interrupt-enable flag. They can also 
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toe selectively masked (that is, some recognized, 
some ignored) by programming the 8259A PIC. 


8259A Programmable Interrupt Controller. A 
"master" 8259A PIC is standard on each 
workstation and controls eight priority interrupt 
levels. Each interrupt level can be connected 
(wire ORed) to one or more device controllers or 
to a "slave" 8259A PIC. The use of slave 8259A 
PICs multiplies the number of external interrupt 
sources that can be uniquely identified and 
ordered in priority. 

Four of the eight interrupt levels are used for 
the standard device controllers of a workstation. 

The other four interrupt levels are available for 
the connection of device controllers that are 
installed in the Multibus-compatible card 
slots. These can be connected directly to the 
four available interrupt levels or can be 
multiplexed through the use of slave 8259A PICs 
installed on logic boards installed in the 
Multibus-compatible card slots. 

Master workstations support large populations of 
cluster workstations by using one or more 
CommlOPs in the Multibus area. The use of other 
Multibus boards requires the implementation of 
user-written device handlers or interrupt 
handlers . 

The 8259A PIC is a flexible hardware entity that 
can operate in a number of modes (see the 
Workstation Hardware Manual). The modes 
established by CTOS initialization are: 


o 

level (not edge) triggered, 


o 

fully nested (but not 

special 

fully nested) 

o 

fixed (not rotating) 

priority, 

and 

o 

not special mask. 




CAUTION: Do not change the mode of the master 

8259A PIC. Changing the mode causes the 

Operating System to malfunction in an 
unpredictable manner. 
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Device handlers and interrupt handlers can only 
perform the following operations on the master 
8259A PIC. (All other operations are forbidden.) 

o They can read the Interrupt Mash Register 
(IMR) of the 8259A PIC; set or clear only the 
bit affecting the interrupt level serviced by 
the handler; and write the updated mash into 
the IMR. 8086 processor interrupts must be 
disabled during this sequence. 

o They can read the Interrupt Request Register 
(IRR) or the Interrupt Service Register (ISR) 
of the 8259A PIC. Because reading either the 
IRR or the ISR requires issuing a command to 
the OCW3 register of the 8259A PIC to select 
the register to be read, 8086 processor 
interrupts must be disabled between selecting 
the register and reading it. 

o Raw interrupt handlers (but not mediated 
interrupt handlers) must issue either a 
specific or nonspecific End-Of -Interrupt 
( EOI ) command to the 8529A PIC before 
returning from the raw interrupt handler to 
the point of interrupt. 

CAUTION; Any other user programming of the 
master 8259A PIC causes the Operating System to 
malfunction in an unpredictable manner. 

Slave 8259A PICs must be completely programmed by 
user code. 


Nomtiashable Interrupts. Nonmashable interrupts 
(NMI) have a higher priority” than maskable 
interrupts. NMIs cannot be masked through the 
use of the processor interrupt-enable flag; 
however, bits in the Input/Output Control 

Register allow each of the four conditions that 
cause NMIs to be masked individually. These 
conditions are: 


o 

write-protect 

violation. 



o 

nonexistent 
reference , 

memory or 

device 

address 

o 

memory parity 

error, and 



o 

power failure 

detection. 
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Internal Interrupts 


Internal interrupts (traps) are caused by and are 
synchronous with the execution of processor 
instructions. The causes of internal interrupts 
are : 

o an erroneous divide instruction (interrupt 
type 0 ) , 

o the 8086 Trap Flag (interrupt type 1? single 
step) , 

o the INTO (interrupt on overflow) instruction, 
if the 8086 Overflow Flag is set (interrupt 
type 4) , and 

o the INT (interrupt) instruction (any 
interrupt type) . 

Pseudointerrupts 


Pseudointerrupts are implemented in software 
rather than in hardware. In this sense, they are 
not really interrupts. However, they are similar 
to interrupts in that they cause an interrupt 
handler to be executed. An interrupt handler 
activated by a pseudointerrupt executes in the 
same environment and has the same 
responsibilities and privileges as an interrupt 
handler activated by a real interrupt. 

As an example of the use of pseudointerrupts, the 
SetTimerlnt operation (see the "Timer Management" 
section) establishes a Programmable Interval 
Timer pseudointerrupt handler to service timer 
pseudointerrupts. Pseudointerrupts, in this 
case, allow each of several software routines to 
believe that it has exclusive use of the high- 
resolution programmable Interval Timer. In a 
master workstation, for example, the Cluster Line 
Protocol Handler, the 3270 Terminal Emulator, and 
a user-written device handler for real-time data 
acquisition equipment would concurrently need 
high-resolution interval timing. Each of the 
three pseudointerrupt handlers performs the same 
logical (but not device-dependent) processing as 
if it were servicing an external interrupt from 
the Programmable Interval Timer itself. 
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Interrupt Handlers 


CTOS interrupt handlers are provided for each 
interrupt type. For interrupt types that are not 
expected to occur, the Extraneous Interrupt 
Handler calls the Crash operation (see the 
"Contingency Management" section) to terminate 
CTOS operation in an orderly manner, display the 
termination code, and restart the OS. 

Each interrupt handler services all interrupts of 
a single type. For example, the interrupt 
handler that services NMIs must accommodate all 
four kinds of NMIs. If another interrupt handler 
is substituted for the Convergent NMI handler, 
the substitute must also handle all four kinds of 
NMIs. 

The OS supports two kinds of interrupt 
handlers: mediated and raw. 


Communications Interrupt Handlers 

Because both SIO communications channels are 
served by type 9 interrupts, the Convergent 
communications interrupt handler should not be 
replaced unless both channels are to be 
controlled by the user-written interrupt 
handler. The Convergent communications interrupt 
handler is required in a cluster workstation, in 
the master workstation of a minicluster 
configuration, or when a communications program, 
such as the Asynchronous Terminal Emulator 
utility or the 3270 terminal emulator, is to be 
used . 

The Convergent communications interrupt handler 
that services type 9 interrupts determines which 
of the two communications channels caused the 
interrupt and dispatches to the appropriate 
Communication Interrupt Service Routine. (See 
"Communications Interrupt Service Routines" 
below . ) 


Packaging of Interrupt Handlers 

Additional interrupt handlers can be linked 
either to a task of an application system or to a 
system service process. The system service 
process can be linked to the System Image at 
system build or dynamically installed. 


Interrupt Handlers 
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Application System. Packaging an interrupt 
handler with an application system permits the 
interrupt handler to occupy memory only when the 
application system that needs it is in memory. 
Also, it requires somewhat less effort to package 
the interrupt handler with an application 
system. An interrupt handler that is used by 
only one application system and not by others 
should generally be packaged with the application 
system. 

The SetlntHandler operation is used to inform the 
OS of the existence of an interrupt handler in an 
application system. 


System Service Process. If an interrupt handler 
must be available continuously, even while one 
application system is being replaced with 
another, then the interrupt handler must be 
packaged with a system service. An interrupt 
handler that supports a device attached to a 
master workstation on behalf of application 
systems executing in cluster workstations must be 
packaged with a system service in the master 
workstation (and must also use the formal 
Request/Respond model of interprocess 
communication) . Packaging an interrupt handler 
with a system service reduces the size of the run 
files of the application systems that would 
otherwise include the interrupt handler. An 
interrupt handler that is used by all or most 
application systems should generally be packaged 
with a system service. 

The SetlntHandler operation is used to inform the 
OS of the existence of an interrupt handler in a 
dynamically installed system service. 


Mediated Interrupt Handlers 

A mediated interrupt handler (MIH) is easier to 
write than raw interrupt handlers (it can be 
written in FORTRAN or Pascal, as well as assembly 
language), permits automatic nesting by priority 
since processor interrupts are enabled during its 
execution, and can communicate its results to 
processes through the PSend and Send 
operations. (See the "Interprocess Communication 
Management" section. ) MIHs are recommended 
except where specifically contraindicated. 
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For an MIH, the entry in the Interrupt Vector 
Table points to a procedure in the Kernel that: 

o saves the hardware context on the stack that 
is active at the time of the interrupt, 

o switches the stack (SS:SP) to a special stack 
that is reserved for the use of MIHs, 

o enables 8086 interrupts (turns on the 8086 
processor interrupt-enable flag), 

o establishes the data segment appropriate to 
the MIH, and 

o calls the MIH at the memory address (CS:IP) 
of its entry point. 

The MIH is responsible for giving an End-Of- 
Interrupt (EOI) command to the slave 8259A PIC, 
if any, on the Multibus board that caused the 
interrupt. However, it must not give an EOI 
command to the master 8259A PIC. 

The only operations an MIH can use are PSend, 
Send, SetTimerlnt, and ResetTimerlnt . (The first 
two operations are described in the "Interprocess 
Communication Management" section; the latter two 
in the "Timer Management" section.) 

After it completes its processing, the MIH 
returns to the Kernel by using a RET (not IRET) 
instruction . 

Upon return from the MIH, the Kernel issues a 
nonspecific EOI command to the master 8259A PIC 
if the interrupt was caused by an external 
maskable interrupt (that is, was caused by the 
8259A PIC) . 

If interrupts are nested and a lower priority 
interrupt handler was interrupted, the Kernel 
unconditionally returns control to the point of 
interrupt (within the lower priority interrupt 
handler) . If the MIH sent a message to a higher 
priority process than the one executing at the 
time of the interrupt, the Kernel establishes 
the context of and returns control to the higher 
priority process. Otherwise, the Kernel 

reestablishes the context of and returns control 
to the interrupted process. 


Interrupt Handlers 29-11 



Raw Interrupt Handlers 


A raw interrupt handler (RIH) provides the 
fastest execution since the entry in the 
Interrupt Vector Table points directly to the 
entry point of the RIH. 

An RIH is useful for servicing a high-speed non- 
DMA device that causes an interrupt whenever a 
byte is to be transferred. To service such a 
device, the RIH saves the minimum number of 
registers, transfers the byte, issues an EOI 
command to the master 8259A PIC (and slave 8259A 
PIC, if appropriate), restores the saved 
registers, and uses the IRET instruction to 
reenable processor interrupts while returning to 
the point of interrupt. 

When the RIH determines (through counting bytes 
or examining the bytes being transferred) that a 
complete logical block was transferred, it 
converts itself to a mediated interrupt handler 
(using the MediatelntHandler operation). It then 
uses the PSend or Send operation to inform the 
device handler (or other) process that the block 
was transferred, issues an EOI command, if 
appropriate, to a slave (but not to the master) 
8259A PIC, and uses a RET (not IRET) instruction 
to transfer control to the Kernel. The Kernel 
then performs the conventional termination 
sequence for a mediated interrupt handler. This 
includes issuing a nonspecific EOI command to the 
master 8259A PIC (but not to a slave 8259A PIC, 
if any) . 

An RIH uses the stack of the process it 
interrupted. It is responsible for saving and 
restoring all registers it uses and for giving an 
EOI command to the master 8259A PIC (and slave 
8259A PIC, if appropriate) . An RIH must leave 
8086 interrupts disabled. Because an RIH cannot 
be interrupted, nesting of interrupts cannot 
occur while an RIH is executing. An RIH can 
serve an internal or external interrupt, but not 
a pseudointerrupt. 

The only operation an RIH can use is Mediatelnt- 
Handler. The MediatelntHandler operation permits 
an RIH to be converted to an MIH during interrupt 
processing. 
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Communications Interrupt Service Routines 


Communications Inter rupt Service Routines (CISR) 
are similar to MIHs except that a CISR serves 
only one of the two communications channels of 
the SIO communications controller. 

CISRs can be linked to the System Image and 
declared at system build. Alternatively, they 
can be linked to a dynamically installed system 
service or an application system and declared 
through the use of the SetCommISR operation. 

CISRs differ from MIHs in that the communications 
channel number (0 or 1) is passed to the CISR as 
a parameter. The CISR must have one parameter 
specified in its procedure definition. For an 
assembly language program, this means that the 
return is by means of an intersegment RET 2 
instruction . 

CAUTION: Read the "Communications Management" 
section of this Manual and the "Communications 
(SIO) Programming" section of the System 
Programmer 1 s Guide to understand the - 
responsibilities of a communications interrupt 
handler with regard to the use of the Lockln and 
Lockout operations, preservation of the "status 
affects vector" mode when programming Channel B 
of the SIO communications controller, and other 
critical issues. 


Printer Interrupt Service Routines 

Printer JEnterrupt Service Routines (PISR) are 
similar to MIHs except that a PISR serves only 
one of several devices connected to the 8259A PIC 
level 4 (interrupt type 12) interrupts. A PISR 
serves parallel printer interrupts without also 
servicing keyboard, Real-Time Clock, and other 
level 4 interrupts. 

PISRs can be linked to the System Image and 
declared at system build. Alternatively, they 
can be linked to a dynamically installed system 
service or an application system and declared 
through the use of the SetLplSR operation. 
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OPERATIONS: PRIMITIVES AND SERVICES 


Interrupt handlers provide the operations listed 

below . 

Med i a telnt Handler 

converts a raw interrupt 
handler to a mediated interrupt 
handler . 

ResetCommISR purges the CISRs previously 

established for the specified 
communications channel. 

SetCommISR establishes the CISRs for the 

specified communications 
channel . 

SetlntHandler establishes a raw or mediated 

interrupt handler. 

SetLpISR establishes the PISR to process 

interrupts generated by the 
parallel printer interface. 
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MediatelntHandler 


Description 


The MediatelntHandler primitive converts a raw 
interrupt handler to a mediated interrupt 
handler. Before using MediatelntHandler, the raw 
interrupt handler must save the contents of the 
registers of the interrupted process on the stack 
of the interrupted process in the following 
order: AX, BX, DS, CX, ES, SI, DX, DI, BP. 

After that, the argument to the call should then 
be saved on the stack. No other information can 
be saved on the stack at the time of the call to 
MediatelntHandler. MediatelntHandler switches 
the stack (SS:SP) to point to the MIH stack. 

Procedural Interface 

MediatelntHandler ( f Devicelnt ) : ErcType 
where 

f Devicelnt is TRUE or FALSE. TRUE (OFFH) 

indicates the interrupt handler 
serves device-generated inter- 
rupts. FALSE (0) indicates the 

interrupt handler serves software- 
generated interrupts (traps). 


Request Block 


MediatelntHandler is a Kernel primitive. 
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ResetConunISR 


Description 


The ResetCommISR service purges the CISRs 
previously established for the specified 
communications channel. Future interrupts from 
the specified channel are ignored. 

Procedural Interface 

ResetCommISR (iLine): ErcType 

iLine is SIO Channel A if iLine is 0 and 

SIO Channel B if iLine is 1. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

2 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

102 

12 

iLine 

2 



29-16 


CTOS" Operating System Manual 




SetCommlSR 


Description 


The SetCommlSR service establishes the CISRs for 
the specified communications channel. Separate 
CISRs are established to process transmit, 
external/status , receive, and special receive 
conditions . 

Procedural Interface 


SetCommlSR (iLine, pDS, pTxIsr, pExtlsr, pRxIsr, 
pSpRxIsr): ErcType 


where 


iLine 

is SIO Channel A if it is 0 and SIO 
Channel B if it is 1. 

pDS 

is the memory address of any byte in 
the memory segment to be used as the 
data segment of the CISRs. The 
segment base address part of pDS is 
to be used as the data segment base 
(that is, loaded into the DS 
register) when any of the four CISRs 
is activated. 

pTxIsr 

is the memory address (CS:IP) of the 
CISR that is to process Transmit- 
Data-Buf fer-Empty interrupts. 

pExtlsr 

is the memory address (CS:IP) of the 
CISR that is to process 
External/Status interrupts. 

pRxIsr 

is the memory address (CS:IP) of the 
CISR that is to process Receive- 
Character-Available interrupts. 

pSpRxIsr 

is the memory address (CS:IP) of the 
CISR that is to process Receive- 
Special-Condition interrupts. 
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Request Block 
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SetlntHandler 


Description 

The SetlntHandler service establishes a raw or 
mediated interrupt handler. When an application 
system terminates, its interrupt handler is 
detached and the default interrupt handler again 
serves the interrupts. 

Procedural Interface 

SetlntHandler (ilnt, plntHandler, saData, 

fDevicelnt, fRaw) : ErcType 

where 

ilnt is the interrupt type (0-119). 

plntHandler is the entry point of the interrupt 
handler. 

saData is the segment base address of the 

data segment that is used by the 
mediated interrupt handler (for 
mediated interrupt handlers only) . 

fDevicelnt is TRUE or FALSE. TRUE ( OFFh) 

indicates the interrupt handler 

serves device-generated inter- 
rupts. FALSE (0) indicates the 

interrupt handler serves software- 
generated interrupts (for mediated 
interrupt handlers only) . 

fRaw is TRUE or FALSE. TRUE (OFFh) 

indicates the interrupt handler 

serves raw interrupts. FALSE (0) 
indicates the interrupt handler 

serves mediated interrupts . 
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Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

12 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

69 

12 

ilnt 

2 


14 

plntHandler 

4 


18 

saData 

2 


20 

fDevicelnt 

2 


22 

fRaw 

2 
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SetLpISR 

Description 


The SetLpISR service establishes the PISR to 
process interrupts generated by the parallel 
printer interface. A PISR established by an 
application system is reset automatically when 
the application system terminates. 

Procedural Interface 

SetLpISR (pLpIsr, saData): ErcType 
where 

saData is the value of the data segment 

(DS), which is used by the printer 
interrupt handler . 

pLpIsr is the memory address (CS:IP) of the 

printer interrupt handler. If it is 
0, it resets the current interrupt 
handler . 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

0 

2 

nReqPbCb 

1 

0 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

121 

12 

saData 

2 


14 

pLpIsr 

4 
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30 CONTINGENCY MANAGEMENT 


OVERVIEW 


Contingency refers to a variety of hardware and 
software conditions that have undesirable 
effects. These conditions can be hardware faults 
such as a memory parity error, OS-detected 
inconsistencies such as a bad checksum of a 
Volume Home Block, or application system-detected 
conditions . 

The OS always terminates execution when it 
detects an inconsistency. The default handling 
of hardware faults (nonmaskable interrupts) is to 
terminate system operation; however, nonmaskable 
(type 2) interrupts can be directed to a user- 
written interrupt handler linked to the System 
Image or declared through the use of the 
Set In t Handler operation (see the "Interrupt 
Handlers" section) . 

CTOS crash conditions are logged in the Log File 
( [Sys]<Sys>Log .Sys) . The OS also logs disk 
controller faults, disk input/output errors, and 
fatal communications errors in the cluster 
configuration there. The application system can 
also use the WriteLog operation to write records 
to the Log File. The PLog utility prints the Log 
File (see the System Utilities Manual). (The Log 
File is also discussed Tn the "File Management" 
section . ) 
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OPERATIONS: PROCEDURES AND SERVICES 


Contingency 
listed below 

Crash 


FatalError 

WriteLog 


management provides the operations 


causes OS operation to 
terminate, a crash dump to be 
written, the OS to be reloaded, 
and the Executive to display 
the cause of the crash when it 
is restarted. 

terminates operation of the 
application system after a 
catastrophic event. 

writes a variable-length record 
to the Log File. 
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Crash 


Description 

The Crash procedure causes OS operation to 
terminate, a crash dump to be written to the file 
[Sys] <Sys>CrashDump. Sys , the OS to be reloaded, 
and the Executive to display the cause of the 
crash when it is restarted. Crash never returns. 

Procedural Interface 

Call Crash ( ercTermination) 

where 

ercTermination 

is a 16-bit status code to be 
displayed by the Executive after the 
OS is reloaded. 

Request Block 

Crash is a system common procedure. 
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FatalError 


Description 

The FatalError procedure terminates operation of 
the application system after a catastrophic 
event. The Convergent-supplied version of 

FatalError consists of a call to the ErrorExit 
operation (see the "Task Management" section). 

Convergent object module procedures call 
FatalError rather than the ErrorExit operation 
when they encounter inconsistencies. This allows 
the system builder to easily substitute a user- 
written version of FatalError that does one of 
the following: 

o invokes the Debugger, 

o calls the Crash operation because it causes a 
crash dump to be written that is useful in 
debugging, 

o calls the Crash operation because the 
application system wants to terminate when it 
malfunctions, or 

o provides special logic to attempt an orderly 
system shutdown when the application system 
detects a malfunction. Such code is best 
included in a user-written version of 
FatalError . 

Procedural Interface 

Call FatalError ( ercTermination) 
where 

ercTermination 

is a 16 -bit status code to be placed 
in the Application System Control 
Block for interrogation by the 
Executive. A nonzero status code 
causes the content of the type-ahead 
buffer to be discarded and the 
submit or recording file to be 
closed. 


Request Block 


FatalError is an object module procedure. 
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WriteLog 

Description 


The WriteLog service is used by an application 
system to write a variable-length record to the 
Log File ( [Sys] <Sys>Log . Sys ) . The PLog utility 
(see the "PLog" section of the System Utilities 
Manual ) prints the Log File. The PLog utility 
interprets the first word of the record as an 
error type; the rest of the record is not 
interpreted. When the record is written to the 
Log File, additional information is inserted by 
the CTOS Operating System. The size of the entry 
in the Log File is the sum of the size of the 
record and the size of the additional 
information. 

Procedural Interface 

WriteLog (pbRecord, cbRecord) : ErcType 

where 

pbRecord 

cbRecord describe the record to be logged. 

Its maximum size is 255 bytes. 


Request Block 


Offset 

Field 

Size 

(bytes) 

Contents 

0 

sCntlnfo 

2 

6 

2 

nReqPbCb 

1 

1 

3 

nRespPbCb 

1 

0 

4 

userNum 

2 


6 

exchResp 

2 


8 

ercRet 

2 


10 

rqCode 

2 

125 

12 

reserved 

6 


18 

pbRecord 

4 


22 

cbRecord 

2 
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APPENDIX A: STATUS CODES 


Codes marked with an * cause CTOS termination and 
an automatic reload. 

Hexa- 

Decimal decimal 
Value Value Meaning 


General 


0 

0000 

OK. 

Successful completion. 

1 

0001 

End of file (EOF) . 

2 

0002 

End of medium (EOM) . 

An attempt to read or write 
beyond the end of a file or 
device . 

3* 

0003 

Inconsistency . 

Run the crash dump analyzer. 

4 

0004 

Operator intervention. 

5 

0005 

Syntax error. 

6 

0006 

Master workstation not running. 
Interstation communication with 
the master workstation of the 
cluster has been interrupted. 

7 

0007 

The procedures necessary to 
implement this operation were 
excluded at system build. 

8 

0008 

An internal inconsistent state 
is discovered. 

10 

000A 

Exchange out of range . 

11 

000B 

Bad pointer. 

12 

oooc 

No link block. 

Generated by PSend . (See the 
"Interprocess Communication 
Management" section.) 


Status Codes 
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Decimal 

Value 

13 

14 

15 

16 

17 

18 

19* 

20 

21 * 

22 * 

23* 

24* 

25* 

26* 


Hexa- 

decimal 

Value Meaning 


000D Bad interrupt vector. 

Generated by SetlntHandler . 
(See the "Interrupt Handlers" 
section . ) 

000E No message available. 

000F No link block available. 

Generated by Send and 
Request. (See the 
"Interprocess Communication 
Management" section.) 

0010 Inconsistent request block. 

0011 Mismatched respond. 

0012 No PCB available. 

Create fewer processes or 
specify more Process Control 
Blocks at system build. 

0013 PIT chain bad. 

Programmable Interval Timer 
block that was established by 
SetTimerlnt was erroneously 
modified. (See the "Timer 
Management" section.) 

0014 Invalid response exchange 
specified in request block. 

0015 Memory protect violation. 

0016 Bus time out. 

Attempted access to a 
nonexistent memory location or 
input/output port. 

0017 Memory parity failure. 

0018 Power failure. 

0019 Unknown NMI . 

001A Stray interrupt. 

Interrupt of unexpected 
interrupt type. 
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Hexa- 


Decimal 

Value 

decimal 

Value 

27* 

001B 

30* 

001E 

31 

001F 

32 

0020 

33 

0021 


34 0022 

Cluster Request Management 

40* 0028 


41 0029 


42 002A 

43* 002B 


Meaning 
Divide error. 

Request table inconsistent. 

No such request code. 

Bad message on default response 
exchange . 

Service not available. 

The request is not ready to be 
served by the system service 
process. The installed system 
service process has to call 
ServeRq to declare its 
readiness to service the 
specified request code. 

Exit run file is not specified. 


Not enough cluster buffer 
memory. 

Initialization error in master 
workstation. Insufficient 
memory is available to allocate 
for cluster buffers. Specify 
smaller data structures at 
system build. 

No available RCB. 

No RCB is available at the 
local CWS Agent Service Process 
to process this request. 

Specify more RCBs at system 
build or modify the application 
system to require fewer 
concurrent requests . 

Agent Srp no room. User- 
defined request block is too 
big for the Agent to handle. 

Bad response from master 
workstation . 

The response from the master 
workstation does not match the 
request . 


Status Codes 
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Decimal 

Value 

Hexa- 

decimal 

Value 

Meaning 


44* 

002C 

Unmatched response at master 
workstation Agent Service 
Process . 

Probably a message was 
erroneously sent to exchange 12 
at the master workstation . 


45 

002D 

Request block too big. 

The request block (with data 
fields expanded) is too big for 
the transmission buffer or line 
buffer. Reduce the size of the 
request or specify larger 
buffers at system build. 


46 

002E 

Master workstation going down . 
Polling of the cluster 
workstation is going to stop. 

Initialization 

100* 

0064 

Memory failure detected during 
initialization . 


101* 

0065 

Insufficient memory for CTOS 
initialization . 


102* 

0066 

No DCB for the device from 
which the OS was bootstrapped. 


103 

0067 

Initialization error. 

The Operating System logs this 
(see PLog in the System 
Utilities Manual) during 
initialization if it finds 
something wrong with the 
keyboard, video display, etc. 

File Management 

201 

00C9 

No free volume structure. 

The Volume Home Block and 
Device Control Block values 
specified at system build are 
inconsistent . 
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Decimal 

Value 


Hexa- 

decimal 

Value Meaning 


202 


203 

204 

205 

206 

207 

208 

209 

210 
211 

212 

213 


214 


00CA Directory full. 

Rename all the files in this 
directory to another directory 
and then delete this 
directory. Create a new 
directory with the name of the 
old directory. Then rename all 
the files from the other 
directory to this new, expanded 
directory . 

00CB No such file. 

00CC No such directory. 

00CD Bad file specification. 

00CE Bad user number. 

The user number should always 
be 0 . 

00CF Bad request code. 

00D0 Duplicate volume. 

00D1 File is read only. 

00D2 Bad file handle. 

00D3 Bad buffer size. 

This must be a multiple of 512 
for disk volumes. 

00D4 Bad logical file address. 

This must be a multiple of 512 
for disk volumes. 

00D5 No free FAB. 

Open fewer files concurrently 
or specify more File Area 
Blocks at system build. 

00D6 No free file number. 

Open fewer files concurrently 
or specify more File Control 
Blocks per User Control Block 
at system build. 
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Hexa- 

Decimal decimal 
Value Value Meaning 


215 


216 

217 

218 

219 

220 


221 


222 


223 


224 

225 


00D7 No such volume or no such 

device . 

The volume is currently not 
mounted . 

00D8 Volume not mounted. 

00D9 Bad password. 

00DA Bad mode. 

00DB Access denied. 

Provide the correct password. 

00DC File in use. 

A process that opens a file in 
modify mode is guaranteed 
exclusive access. Only one 
file handle can refer to a file 

that is open in modify mode. 

00DD File Header bad checksum. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00DE File Header bad page number. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00DF File Header bad header number. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00E0 File already exists. 

00E1 No free File Headers. 

Run Backup Volume, IVolume (and 
specify more File Header 
Blocks), and Restore on this 
volume. 
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Decimal 

Value 

226 

227 

228 

229 

230 

231 

232 

233 

234 

235 

236 

237 

238 


Hexa- 

decimal 

Value Meaning 


00E2 Free File Headers broken. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00E3 Device in use. 

00E4 Device already mounted. 

00E5 Device not mounted. 

00E6 Disk full. 

There are not enough available 
disk sectors to accommodate the 
current CreateFile or 
ChangeFileLength request. 

00E7 Not a device that can be 
mounted . 

00E8 No valid VHB . 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

G0E9 File Header bad file name. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00EA Odd byte buffer address. 

The buffer must be word- 
aligned. 

00EB Wrong volume mounted. 

00EC Bad device specification. 

00ED Directory page invalid. 

The volume control structures 
are invalid. Run Backup 
Volume, IVolume, and Restore on 
this volume. 

00EE Request not valid for device. 


Status Codes 


A- 7 



Decimal 

Value 

239 

240 

241 

242 

243 


244* 


245 

246 

247 


Hexa- 

decimal 

Value Meaning 

00EF Wrong volume destination. 

Rename cannot move a file to 
another volume. 

00F0 Directory already exists. 

00F1 Directory not empty. 

00F2 MFD is full. 

Run Backup Volume, IVolume (and 
specify more sectors for the 
Master File Directory), and 
Restore on this volume. 

00F3 Verify error. 

A volume control structure 
( VHB, FHB , etc.) was written 
and then immediately reread to 
verify that it was written 
correctly. The information 
reread does not compare with 
the information written, 
although the disk controller 
did not report an error. Error 
243 indicates a serious disk 
controller, DMA, or memory 
hardware malfunction. 

00F4 System device not ready. 

If a swapping OS was 
bootstrapped from a floppy 
disk, then the OS floppy disk 
cannot be removed from the 
drive . 

00F5 Run file bad checksum. 

The file is probably not a run 
file . 

00F6 Bad run file. 

The file is probably not a run 
file. 

00F7 Old format run file. 

The file is probably not a run 
file . 


A-8 CTOS™ Operating System Manual 



Hexa- 

Decimal decimal 
Value Value Meaning 


248 


249 


250 


251 

252 


253 


254 


290 


00F8 Wrong pRq argument. 

CheckReadAsync or 
CheckWriteAsync does not agree 
with the preceding ReadAsync or 
WriteAsync . 

00F9 Invalid attributes for 

secondary task. 

A task loaded with LoadTask (as 
opposed to Chain) cannot use 
virtual code segments or have a 
memory array. (See the 
Linker /Librarian Manual and the 
"Task Management" section.) 

00FA Too many runs . 

The file cannot be expanded 
because it already contains the 
maximum number of runs. The 
maximum number of runs per file 
is a system build parameter. 

00FB Cannot write to the 

[ Sys ] < Sy s > Log . 

00FC Cannot open the OS image file 
for the swapping cluster 
workstation . 

00FD Cannot read the OS overlay for 

the swapping cluster 
workstation . 

00FE All the user numbers on the 

master workstation have been 
used. Change the system build 
parameter for the User Control 
Block (multiple application 
partitions only) . 

0122 Log buffer overflow. 

Multiple errors occurred 
rapidly and the Operating 
System was unable to log all of 
them. 


Status Codes A- 9 



Hexa- 

Decimal decimal 
Value Value Meaning 


Device Management 


300 


301 


302 


303 


01 2C Device not ready. 

Make sure that the power is on 
and that there is a floppy disk 
in the disk drive. 

01 2D I/O error. 

If you are using a floppy disk, 
the disk is bad and should be 
replaced with another disk. 

01 2E Write protected. 

There is no write enable tab on 
the floppy disk. 

01 2F No free IOB. 

There are too many concurrent 
input/output operations. More 
I/O Blocks should be specified 
at system build. 


Floppy Disk Controller 

(See the Peripherals Hardware Manual for more information.) 

These codes relate to hardware controller 
failure. Code 3 28 (decimal) may result ''from a 
failure to include all floppy disks in the system 
build . 


320 

0140 

Floppy disk controller 
command . 

busy in 

321 

0141 

Floppy disk controller 
ready in command . 

never 

322 

0142 

Floppy disk controller 
input in command. 

data 

323 

0143 

Floppy disk controller 
ready in result. 

never 

324 

0144 

Floppy disk controller 
input in result. 

not data 

325 

0145 

Floppy disk controller 
after Xfer request. 

not busy 
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Hexa- 

decimal 

Value 

Meaning 

326 

0146 

Floppy disk controller wrong 
unit after Xfer request. 

327 

0147 

Floppy disk controller busy 
without Xfer request. 

328 

0148 

Floppy disk controller 
interrupt from undefined unit. 

329 

0149 

Floppy time out. 

330 

01 4A 

Incomplete DMA transfer to/ from 
floppy disk. 


Hard Disk Controller 

(See the Peripherals Hardware Manual for more information.) 

These codes relate to hardware controller 
failure. Code 348 (decimal) may result from a 
failure to include all Winchester disks in the 


system 

build . 



340 

0154 

Hard disk controller 
command . 

busy in 

341 

0155 

Hard disk controller 
ready in command . 

never 

342 

0156 

Hard disk controller 
in command . 

data input 

343 

0157 

Hard disk controller 
ready in result. 

never 

344 

0158 

Hard disk controller 
input in result. 

not data 

345 

0159 

Hard disk controller 
after Xfer request. 

not busy 

346 

01 5A 

Hard disk controller 
after Xfer request. 

wrong unit 

347 

0.1 5B 

Hard disk controller 
without Xfer request. 

busy 

348 

015C 

Hard disk controller 
from undefined unit. 

interrupt 


Status Codes A- 11 





Hexa- 

Decimal decimal 
Value Value 

Meaning 



349 

015D 

Hard disk time out. 



350 

015E 

Incomplete DMA transfer to/ from 
hard disk. 



351 

015F 

Bad hard disk controller. 

Allocation 






400 

0190 

Not enough memory available to 
satisfy memory allocation 
request . 



401 

0191 

Cannot allocate long-lived 
memory. 

The memory cannot be allocated 
because the Debugger is locked 
into memory in multiple-process 
or interrupt mode. (See the 
Debugger Manual . ) 



402 

0192 

Invalid memory segment 
specification to 
DeallocMemorySL/LL. 

(See the "Memory Management" 
section . ) 



410 

019A 

All exchanges already 
allocated . 

Specify more exchanges at 
system build. Also caused by 
too many files listed in the 
Submit command. Submit fewer 
files at a time. 



411 

019B 

Invalid exchange identification 
specified to DeallocExch. 

(See the "Exchange Management" 
section . ) 

Timer 

Management 





420 

01A4 

Too many RTC requests. 

Specify a bigger Real-Time 
Clock request table at system 
build . 



421 

01A5 

Invalid timer block 
specification in CloseRTClock. 
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Task Management 


Hexa- 

Decimal decimal 
Value Value Meaning 


430* 01AE 


431 01AF 

Video Display Manager 

500 01F4 

501 01F5 

502 01F6 

503 01F7 

504 01F8 

505 01F9 

Keyboard Management 

601 0259 

602 025A 

603 025B 


Cannot load Executive. 

The Debugger is locked in 
memory, [Sys] < Sys> Exec . Run is 
bad, or the memory 
specifications at system build 
were erroneous. 

The printer ISR already exists. 


Frame number/coordinates do not 
agree with the VCB. 

Invalid argument to VDM. 

Video buffer is not word- 
aligned . 

VCB not completely initialized. 

Video DMA hardware failure. 

Too many attributes on a line 
( AWS workstation only) . 


Duplicate ReadKbd or 
ReadKbdDirect . 

Only one ReadKbd or 
ReadKbdDirect request can be 
outstanding at a time. 

No character available. 
ReadKbdDirect specified not to 
wait for a character and no 
keyboard character/code is 
currently available. 

Invalid escape sequence in 
submit file. 


Status Codes A-13 




Hexa- 


Decimal decimal 


Value 

Value 

Meaning 

604 

025C 

Invalid argument to a Keyboard 
operation. 

605 

025D 

Invalid mode code to 
SetSysInMode . 

606 

025E 

Failure of 8048 keyboard 
microprocessor . 

607 

025F 

Reserved . 

608 

0260 

Application system being 
terminated by request of 
another process or ACTION- 
FINISH. 

609 

0261 

No action code available. 
ReadActionCode returns this 
status if the workstation 
operator has not entered an 
action code. 

610 

0262 

Type-ahead buffer overflow. 

Printer Spooler 

700 

02BC 

A Conf igureSpooler operation 
attempted to free a printer 
that was not attached . 

701 

02BD 

A SpoolerPassword operation 
attempted to enter a password 
when the printer spooler was 
not waiting for a password. 

702 

02BE 

Invalid printer name specified 
in a SpoolerPassword operation. 

703 

02BF 

Invalid channel number 
specified in a Conf igureSpooler 
operation . 

704 

02C0 

A Conf igureSpooler operation 
attempted to add a new printer 
to a channel that is not free 

705 

02C1 

Invalid printer spooler 
configuration file specified in 
a Conf igureSpooler operation. 

A-14 CTOS" Operating 

System Manual 



Decimal 
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Hexa- 

decimal 

Value Meaning 


706 02C2 A spooler was installed with a 

printer name which was already 
in use. Printer names must be 
unique. 


Application Partition Management 

800 0302 

801 0303 

802 0304 

803 0305 

804 0306 

805 0307 

806 0308 

807 0309 


808 030A 

809 030B 

810 030C 


Application partition is not 
vacant. Vacate the partition 
first. 

Cannot create any more 
application partitions. Number 
of application partitions is a 
system build parameter. 

Partition name is duplicated. 
Default name for the first 
application partition is ' bkg.' 

Invalid partition handle is 
specified . 

Invalid partition name is 
specified. Indicates too many 
characters or illegal 
characters . 

Application partition is 
vacant . 

Application partition is 
locked. A task on a locked 
partition cannot be terminated. 

Application partition is not 
locked. The partition should 
be locked before using the 
SetPartitionExchange operation. 

Partition exchange has not been 
set . 

Partition exchange has already 
been set. 

An Assign statement in JCL file 
is attempted when the assign 
table is full. 


Status Codes A-15 



Hexa- 

Decimal decimal 
Value Value Meaning 


Queue Management 


900 


901 


902 


903 


904 


905 


906 


907 


0384 A DeleteMarkedQueueEntry , 
UnmarkQueueEntry , or 
RewriteMarkedQueueEntry 
operation was invoked with an 
invalid queue entry handle 
(qeh). The qeh specified was 
for an entry that is not 
marked . 

0385 A DeleteKeyedQueueEntry 

operation specified an entry 
that was previously marked. 

0386 A DeleteKeyedQueueEntry, 

ReadKeyedQueueEntry , or 
MarkKeyedQueueEntry operation 
was invoked for which no 
matching entry was found. 

0387 A MarkNextQueueEntry operation 

was invoked when no entries 
were available. 

0388 The ReadNextQueueEntry 
operation specified an entry 
that was deleted since its 
queue entry handle was 
returned . 

0389 The pb/cbQueueName fields of an 

operation specifies an invalid 
queue . 

038A An EstablishQueueEntry 

operation was invoked when 100 
server processes were already 
established . 

038B A Marking operation was invoked 

by a server process that had 
not invoked an 

EstablishQueueServer operation. 
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Value Value Meaning 


908 


909 


910 


91.1 

912 


913 


914 


038C An AddQueueEntry operation was 

involved with the 
fQueuelfNoServers flag set to 
FALSE when no server processes 
were established. 

038D A DeleteMarkedQueueEntry, 
UnmarkQueueEntry, or 
RewriteMarkedQueueEntry 
operation was invoked with an 
invalid queue entry handle. 

038E A DeleteMarkedQueueEntry, 

UnmarkQueueEntry, or 
RewriteMarkedQueueEntry 
operation was invoked by a 
server process other than the 
server process that marked the 
entry . 

038F A syntax error was made when 

opening the queue index file. 

0390 An AddQueueEntry operation 
specifies a queue type that 
does not match the queue type 
in the queue index file. 

0391 An AddQueueEntry operation was 
invoked with an invalid 
date/time specification. 

0392 The server process specified in 

an EstablishQueueServer 
operation is already 
established as a server. 


Debugger 

(See the Debugger Manual for more information.) 

1001 03E9 Cannot convert from simple mode 

to multiple-process mode. To 
enter multiple-process mode, 
first exit the Debugger and 
then press ACTION-B . 


Status Codes A-17 



Hexa- 

Decimal decimal 
Value Value Meaning 


1002 


1003 


1004 


1005 


03EA Not enough memory for multiple- 
process mode or CODE-I 
breakpoint. Approximately 37k 
of memory must be available to 
enter multiple-process mode or 
set a CODE-I breakpoint. 

03EB Cannot deactivate Debugger. 

The Debugger cannot be 
deactivated while CODE-I 
breakpoints are set or while a 
breakpoint has just executed. 

To deactivate the Debugger, 
first remove all CODE-I 
breakpoints and/or proceed 
(single step) from the 
breakpoint . 

03EC Breakpoint already there. 

The Debugger allows only one 
breakpoint per location. 

03 ED Debugger crash. 

A fatal internal error has 
occurred. Press the RESET 
button on the back of the 
workstation . 


Sequential Access Method 

2305 0901 

2315 090B 

2325 0915 

2335 091F 

2336 0920 


Too many put backs . 

Only one PutBackByte is allowed 
before reading again. 

Invalid mode to OpenByteStream . 

Invalid BSWA. 

BSWA has been erroneously 
modified by the user or a byte 
stream was not opened for BSWA. 

Buffer too small. 

Buffer must be 1024 bytes to 
allow device independence. 

Invalid video byte stream 
escape sequence. 
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Value 


2340 


2341 


2342 


2343 


2344 


Hexa- 

decimal 

Value Meaning 

0924 Parity error detected on the 
last byte received by the 
communications byte stream. 

All bytes, except the last one, 
returned from the read 
operation were received without 
error . 

0925 Receive overrun error detected 
on the last byte received by 
the communications byte stream. 
All bytes, except the last one, 
returned from the read 
operation were received without 
error. 

0926 Framing error detected on last 
byte received by the 
communications byte stream. 

All bytes, except the last one, 
returned from the read 
operation were received without 
error . 

0927 Wrong configuration type. 

The specified configuration 
file is not of the type 
expected for the device 
specified . 

0928 Bad configuration file. 

There was an error in accessing 
the appropriate configuration 
file. Either the specified 
configuration file (or the 
default if one was not spec- 
ified) does not exist or an 
error was encountered when 
trying to read the file. 


Status Codes A-19 




Hexa- 


Decimal 

decimal 


Value 

Value 

Meaning 

X. 25 Sequential Access 

Method 


2350 

092E 

X. 25 error occurred during 
operation. 

If an X . 25 error occurs during 
a byte stream operation, the 
call is cleared, but the byte 
stream is not closed. A 
ReleaseByteStream or CloseByte- 
Stream operation must be done 
to close the byte stream. 

2351 

092F 

Time out. 

The specified time out elapsed 
before the X.25 Network Gateway 
system service operation fin- 
ished. The operation in ques- 
tion is terminated, but the 
call is not cleared. 

Parameter Management 

2440 

0988 

No such iParam. 

The value of iParam supplied to 
RgParam is not less than 
CParams . 

2450 

0992 

No such jParam. 

The value of jParam supplied to 
RgParam is not less than 
CSubparams (iParam). 

2470 

09A6 

VLPB full. 

The operation failed because 
the Variable Length Parameter 
Block could not be extended by 
allocating long-lived memory. 

2480 

09B0 

Illegal iParam. 

The value of iParam supplied to 
RgParamSetListStart or 
RgParamSetSimple is not less 
than CParams . 
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Value Value Meaning 

2490 09BA Not in list. 

RgParamSetEltNext was invoked 
after a RgParamSetListStart or 
RgParamSetSimple other than 
RgParamSetListStart or 
RgParamSetEltNext . 

Date/Time Conversion 

2700 0A8C Year out of range 1952-2042. 

2701 0A8D Day not valid for specified 

month. 

Must be 1 to 28/29/30/31 as 
appropriate . 

2702 0A8E Date and day of week disagree. 
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Decimal 

Value 

Hexa- 

decimal 

Value 

Meaning 

2703 

0A8F 

Invalid time of day 
specification. 

Direct Access Method 



3000 

0BB8 

DAWA in use. 

OpenDaFile failed because the 
DAWA is currently associated 
with another DAM file. 

3001 

0BB9 

Not readable by DAM. 

OpenDaFile failed because the 
specified file contains records 
that cannot be read by the 
DAM. For example, the file can 
contain variable-length 
records . 

3002 

OBBA 

sRecord mismatch. 

OpenDaFile failed because the 
sRecord parameter did not match 
the sRecord specified when the 
file was created. 

3003 

OBBB 

DAM internal error. 

The operation failed because an 
internal inconsistency was 
detected . 

3004 

OBBC 

DAWA invalid. 

The operation failed because 
pDAWA specified an invalid 
DAWA. A DAWA is invalid if it 
is not recognized as a DAWA or 
if it is not associated with an 
open file. 

3005 

OBBD 

Bad record fragment. 
ReadDaFragment or 
WriteDaFragment failed because 
the record fragment exceeds the 
record bounds . 

3006 

OBBE 

Bad buffer mode. 

SetDaBuf ferMode failed because 
an invalid buffer mode was 
given. 



Status Codes A-21 



Hexa- 

Decimal decimal 

Value Value Meaning 

3007 OBBF Record beyond existing records. 

The operation, failed because 

the specified record does not 

exist. This status code is 
equivalent to ercRecordDoesNot- 
Exist (code 3302) except that 
this code (that is, 3007) 
provides this additional 
information; the record is 
beyond any existing record. 

Indexed Sequential Access Method 

(See the ISAM Manual for more information.) 

3100 0C1C No such index. 

The specified key field does 
not exist. 

3101 0C1D Prefix not valid. 

The type of index specified to 
SetupISAMIterationPrefix is 
neither byte string nor 
character string. 

3102 0C1E Bad key length. 

The length of the key is 
inconsistent with the type of 
the index. 

3103 0C1F Bad ISAM handle. 

The ISAM handle does not 
identify an open ISAM data set. 

3104 0C20 Bad ISAM header size. 

The ISAM data set cannot be 
opened by OpenISAM due to an 
inconsistency in the header of 
one of the files of the data 
set . 

3105 0C21 Bad ISAM header. 

The ISAM data set cannot be 
opened by OpenISAM due to an 
inconsistency in the header of 
one of the files of the data 
set . 
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3106 


3107 


3108 


3109 


3110 


3111 


Hexa- 

decimal 

Value Meaning 


0C22 Too many indexes. 

The number of indexes in the 
data set created by CreatelSAM 
or opened by OpenISAM is larger 
than the clndexesMax parameter 
of InstalllSAM or the number 
specified in [Maximum no. of 
indexes in any ISAM data set 
(default 10)] of ISAM Install. 

0C23 ISAM already installed. 

This code is generated by 
InstalllSAM or ISAM Install if 
ISAM is already installed. 

0C24 Not enough DGroup memory. 

The memory area specified by 
the oDGroupMemory and 
sDGroupMemory parameters of 
InstalllSAM is not large 
enough, or not enough short- 
lived memory can be allocated 
for DGroup memory, or the 
values of the parameters of 
InstalllSAM require allocation 
of more than 64,435 bytes of 
DGroup memory. 

0C25 Not addressable from DS. 

The short-lived memory 
allocated by InstalllSAM for 
DGroup memory is not 
addressable from the DS (data 
segment) register of the 
invoking process. 

0C26 No free ISAM Control Blocks. 

All the ISAM Control Blocks are 
in use. Reinstall ISAM with 
more ISAM Control Blocks. 

0C27 No free ISAM User Blocks. 

All the ISAM User Blocks are in 
use. Reinstall ISAM with more 
ISAM User Blocks. 
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Decimal decimal 
Value Value Meaning 


3112 


3113 


3114 


3115 


3116 


3117 


3118 


3119 


0C28 No free ISAM Index 

Specification Blocks. 

All the ISAM Index 
Specification Blocks are in 
use. Reinstall ISAM with more 
ISAM Index Specification 
Blocks . 

0C29 Buffers too large. 

The amount of memory required 
by the buffer sizes specified 
to InstalllSAM or to ISAM 
Install exceeds one megabyte. 

0C2A Bad pCacheBuf fers . 

The relative address part of 
the pCacheBuf fers parameter of 
InstalllSAM is nonzero. 

0C2B ISAM crashed. 

This code is generated by all 
ISAM operations upon detection 
of an internal error. 

0C2C ISAM not installed. 

This code is generated by all 
ISAM operations before 
InstalllSAM is called or ISAM 
Install is successfully 
executed . 

0C2D Bad unique record identifier. 

An incorrect unique record 
identifier parameter was passed 
to ISAM. 

0C2E Duplicate key. 

A StorelSAMRecord or 

ModifylSAMRecord was attempted 
with the value of a key field 
that duplicates the field in 
another record . 

0C2F Index file error. 

This is returned as the status 
code of an ISAM operation. The 
detail status code refers to a 
problem with the index file of 
the ISAM data set. 
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3120 


3121 


3122 


3123 


3124 


3125 


3126 


3127 


0C30 Attempted privacy breach. 

An attempt was made to modify a 
data set which is open in batch 
read or transaction read mode. 

0C31 Bad ISAM request. 

The parameters of an ISAM 
operation are inconsistent or 
have invalid values. 

0C32 Data store file error. 

This is returned as the status 
code of an ISAM operation. The 
detail status code refers to a 
problem with the data store 
file of the ISAM data set. 

0C33 Index to data error. 

An inconsistency has arisen 
between the index and data 
store files of the ISAM data 
set . 

0C34 Record size incorrect. 

The record size specified is 
incorrect for the ISAM data 
set . 

0C35 Duplicates allowed. 

An attempt was made to use 
ReadUniquelSAMRecord for keys 
for which duplicates are 
allowed . 

0C36 No such record. 

An attempt was made to use 
ReadUniquelSAMRecord to read a 
record that does not exist. 

0C37 No more records. 

An attempt was made by 
ReadNextISAMRecord or 
GetlSAMRecords to read more 
records than those specified to 
SetupISAMIterationKey , 
SetupISAMIterationPrefix, or 
SetupISAMIterationRange . 
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Decimal decimal 
Value Value Meaning 


3128 

3129 

3130 

3131 

3132 

3133 

3134 

3135 

3136 


0C38 Bad key. 

A key does not correspond to 
the index type. (For example, 
each digit of a BCD key must be 
between 0 and 9 . ) 

0C39 Bad index. 

The specified key field does 
not exist. 

0C3A Bad ISAM mode. 

OpenISAM detects a bad mode. 

0C3B Cannot open ISAM. 

This is returned as the status 
code of an ISAM operation. The 
detail status code gives the 
reason for the failure. 

0C3C Bad ISAM password. 

The password does not give the 
access desired by OpenISAM, or 
the password is larger than the 
12 bytes accepted by 
SetlSAMPasswords . 

0C3D Wrong size record. 

OpenISAM detects the wrong size 
record . 

0C3E Incompatible ISAM mode. 

An attempt was made to open a 
data set when the data set is 
already open in an incompatible 
mode . 

0C3F ISAM already locked. 

LockISAM was invoked while an 
ISAM data set is locked by the 
user . 

0C40 Not administrator. 

An operation for which the data 
set must be open in 
administrator mode was 
attempted with the data set 
open in some other mode. 
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3137 


3138 


3139 


3140 


3141 


3142 


3143 


3144 


0C41 Cannot create ISAM. 

This is returned as the status 
code of CreatelSAM. The detail 
status code gives the reason 
for the failure. 

0C42 ISAM buffer too small. 

The data set being opened or 
created requires buffers larger 
than those installed. 

0C43 Not locked. 

An attempt was made in 
transaction mode to call an 
ISAM operation other than 
CloselSAM for a data set that 
is not locked. 

0C44 Small ISAM Record. 

An attempt was made to create 
an ISAM data set with records 
shorter than four bytes. 

0C45 Not in transaction. 

An operation was invoked for 
which the user must be in a 
transaction, but the user was 
not in a transaction. 

0C46 Data set not available. 

An attempt was made to read or 
hold a record, or to hold a 
data set, without queueing, and 
the data set was held by 
another user. 

0C47 Record not available. 

An attempt was made to read or 
hold a record without queueing, 
and the record was held by 
another user. 

0C48 Record not held. 

An operation for which the 
record (or its data set) must 
be held was invoked when 
neither the record nor its data 
set was held. 
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3145 


3146 


3147 


3148 


3149 


0C49 Too many records held. 

An attempt was made to hold a 
record when the maximum 
allowable number of records are 
already held. 

0C4A In transaction. 

StartlSAMTransaction was 
invoked during a transaction. 

0C4B Request pending. 

A transaction operation other 
than PurgelSAMTransaction was 
invoked when one or more 
requests were queued for the 
user . 

0C4C Transaction purged. 

PurgelSAMTransaction was 
invoked while the request was 
queued . 

0C4D Not enough buffers. 

InstalllSAM (or the ISAM 
Install command) was invoked 
specifying fewer than two data 
store buffers or three index 
buffers. Specify at least two 
data store buffers and three 
index buffers. 


3170- 0C62- 

3199 0C7F Internal ISAM errors. 


Key-in-Record 

(See the Sort/Merge Manual or the ISAM Manual , as appropriate, 
for more informationT) 

3200 0C80 Bad key type. 

The type field of a key 
specification for Sort/Merge or 
ISAM is invalid. 
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3201 0C81 


3202 0C82 


Standard Access Methods 


Incorrect key length. 

The cbKey field of a key 
specification for a Sort/Merge 
or ISAM operation does not 
correspond to the type field of 
the key specification. (For 
example, for binary keys, cbKey 
must be 2 . ) 

Bad key . 

A key contained in a record for 
Sort/Merge or ISAM, or a key 
described by a parameter of an 
ISAM operation, is not of the 
correct type. (For example, 
each digit of a BCD key must be 
between 0 and 9 . ) 


3300 


3301 


3302 


3303 


3304 


0CE4 Not a STAM file. 

The operation failed because 
the file did not contain the 
proper signature. 

0CE5 STAM header bad checksum. 

The operation failed because 
the checksum computed on the 
file header did not match the 
checksum computed when the file 
was created. 

0CE6 Record does not exist. 

The operation failed because 
the specified record does not 
exist . 

0CE7 Malformed record. 

The operation failed because 
data read from the disk 
contained an inconsistency in 
the record header and trailer. 

0CE8 Not fixed-length record. 

The operation failed because 
the access method cannot 
reference variable-length 
records . 


Status Codes A-29 



Hexa- 

Decimal decimal 
Value Value 

3305 0CE9 

3306 OCEA 

3307 OCEB 

External-Key Sort 
(See the Sort/Merge Manual for 

3400 0D48 

3401 0D49 

3402 0D4A 


3403 0D4B 

3404 0D4C 

3405 0D4D 


Meaning 

Bad file type. 

The operation failed because 
the file cannot be accessed 
with the specified access 
method . 

Bad buffer size. 

The operation failed because 
the buffer size was too small 
or not a multiple of 512. 

Buffer not word-aligned. 

The operation failed because 
the buffer was not word- 
aligned . 


more information.) 

Cannot open work file. 

Unable to open one of the work 
files during PrepareSort. 

Work area bad. 

Unable to allocate work area 
during PrepareSort. 

Bad key size. 

A key passed to 
ReleaseRecordAndKey is a 
different length than the 
length specified in 
PrepareSort . 

File error during sort. 

A file error occurred during 
the sort phase of the program. 

No more records. 
ReturnRecordAndKey was called 
after all records were 
retrieved. 

Error returning record. 

An error occurred in 
ReturnRecordAndKey . 
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Value Value Meaning 

3406 0D4E Error during conclude. 

An error occurred in 
ConcludeSort or TerminateSort. 

3407 0D4F More records available. 

ConcludeSort was called before 
all records were retrieved. To 
end a sort prematurely, call 
TerminateSort . 

3408 0D50 Record too large. 

The size of a record is larger 
than the maximum key size 
specified in PrepareSort or the 
sort area is not large enough. 

3409 0D51 Error during sort. 

An error occurred during 
DoSort . 

3410 0D52 Insufficient memory. 

Not enough memory was allocated 
for the sort work area. 

3411 0D53 No records to sort. 

DoSort was called before any 
records were released. 

Key-in-Record Sort 

(See the Sort/Merge Manual for more information.) 

3500 0DAC Sort pending. 

PrepareKeySort was called while 
a sort was already active. 

3501 0DAD No sort pending. 

A sort procedure other than 
PrepareKeySort was called 
before PrepareKeySort. 

3502 0DAE Bad sort key. 

The key provided is 
inconsistent with its 
specifications . 


Status Codes 


A-31 



Decimal 

Value 

Hexa- 

decimal 

Value 

Meaning 

3503 

ODAF 

Sort key not in record. 

A key could not be synthesized 
from this record, given the 
initial specifications of keys 
within records . 

3504 

0DB0 

Bad key specification. 

The key specification in 
PrepareKeySort is incorrect. 
It conflicts with the maximum 
record size provided. 

Record Sequential Access 

Method 


3600 

0E10 

RSWA in use. 

OpenRsFile failed because the 
RSWA is currently associated 
with another RSAM file. 

3601 

0E1 1 

RSWA invalid. 

The operation failed because 
pRSWA specified an invalid 
RSWA. An RSWA is invalid if it 
is not recognized as an RSWA or 
if it is not associated with an 
open file. 

3602 

0E1 2 

RSAM internal error. 

The operation failed because an 
internal inconsistency was 
detected . 

3603 

0E1 3 

Bad mode . 

OpenRsFile failed because the 
mode parameter was invalid. 

3604 

0E14 

Not readable by RSAM. 
OpenRsFile failed because the 
specified file cannot be read 
by RSAM. 

3605 

0E15 

Wrong mode . 

The mode, which was specified 
when the file was opened, does 
not allow the operation to 
succeed. For example, mode 
read does not allow 
WriteRsRecord to succeed. 
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Value Value Meaning 

3606 0E16 Record too large. 

The record is too large to fit 
into the buffer supplied by 
ReadRsRecord . 

3607 0E17 Good record not found. 

ScanToGoodRsRecord was unable 
to locate a well- formed record. 

Forms 

(See the Forms Manual for more information.) 

3700 0E74 Name not found. 

The form name supplied to 
OpenForm was not found within 
the file. Check that the file 
name and form name are correct 
for the form you want. 

3701 0E75 Bad object file. 

The file supplied to OpenForm 
does not appear to be a valid 
object module. Possibly the 
file is empty. Check that the 
file name is correct for the 
form you want. 

3702 0E76 Form too big. 

The work area supplied to 
OpenForm was too small to 
contain the named form. Use 
FReport to learn the size of 
the required work area, and 
make sure you have allocated 
sufficient space. 

3703 0E74 Form out of bounds. 

The screen coordinates passed 
to DisplayForm would result in 
a part of the form lying 
outside the frame. Use FReport 
to learn the required height 
and width, and make sure that 
the frame number and 
coordinates within the frame 
are correct for these values. 


Status Codes A- 3 3 



Decimal 

Value 


3704 


3705 


3706 


3707 


Hexa- 

decimal 

Value Meaning 


0E78 Form not displayed. 

A Forms run-time operation 
(DefaultField, DefaultForm, 
ReadField, SetFieldAttrs , 
UndisplayForm, UserFillField, 
or WriteField) was attempted on 
a form that had not been 
displayed with DisplayForm. 

Make sure that the form was 
displayed before attempting any 
of these operations. 


0E79 No such field. 

A Forms run-time operation 
(DefaultField, GetFieldlnfo, 
ReadField, SetFieldAttrs, 
UserFillField, or WriteField) 
was attempted for which the 
field specified by pbFieldName, 
cbFieldName, and index does not 
exist. Use FReport to display 
the names and allowable indexes 
for all fields, and make sure 
the field specification you 
have supplied is correct. 

0E7A Bad type specification. 

ReadField or WriteField was 
supplied with a type code that 
is not defined in your 
configuration. Examine the 
source text of FmRgtd.Asm for a 
list of defined type codes, and 
make sure that the codes you 
are supplying are in this list. 

0E7B Bad data size. 

ReadField was attempted in 
which the cbMax parameter was 
incorrect for the type of data 
being returned, for example, a 
cbMax of three for type 
"Binary." Make sure that the 
size and type of your data area 
agree . 
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Decimal decimal 

Value Value Meaning 

3708 0E7C Invalid data. 

ReadField or WriteField was 
attempted in Which the 
requested data conversion could 
not be performed, for example, 
reading an alphabetic string as 
type "Binary." For WriteField, 
make sure the type of the data 
you are displaying is 
correct. For ReadField, it is 
probably appropriate to display 
an error message and have the 
user reenter the data. 

Virtual Code Segment Management 

7301 1C85 Overlay too large. 

The overlay is too large to fit 
into the overlay area. The 
size of the overlay area must 
be increased or smaller 
overlays used. 

7302 1C86 Not enough room for Virtual 

Code Segment Manager data. 

The overlay area cannot 
accommodate the data required 
by the Virtual Code Segment 
Manager. The size of the 
overlay area must be increased. 

7303 1C87 Unable to read overlay. 

The Virtual Code Segment 
Manager is unable to read the 
overlay from the run file. The 
run file should be verified. 


7304 1C88 Inconsistent overlay 

information. 

The overlay information 
contained in the run file is 
inconsistent. The run file may 
be malformed. 


Status Codes A-35 



Decimal 

Value 


Hexa- 

decimal 

Value 


Meaning 


Communications 

8002 1F42 Lost clear to send during 

transmission . 

This generally indicates a 
modem problem. 

8003 1F43 Lost carrier during reception. 

This indicates a problem with 
the modem or transmission 
facilities, or at the host 
computer site. 


Master/Cluster Workstation Communications 


8100 1FA4 


8101* 1FA5 

8102* 1FA6 

8103* 1FA7 


Time out. 

A workstation no longer 
responds to polling. 

In the context of 2780/3780, 
8100 also means: the host 

computer failed to respond to a 
transmission . 

Possibly indicates a total 
break in communications. 

Invalid state. 

Run the crash dump analyzer. 

Communications hardware 
failure. 

Run the communications 
diagnostic . 

Unrecoverable protocol failure 
detected by the master 
workstation . 

A cluster workstation has 
ceased to obey proper protocol 
procedure and has defied all 
attempts to recover (including 
an attempt to refuse 
communication with the master 
workstation) . This can be 
caused by a hardware failure 
(including cabling) or 
excessive DMA loading. 
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Decimal 

Value 


8104* 


8105 


8106 


8109* 


8111 


Hexa- 

decimal 

Value Meaning 


1FA8 Bad DMA buffer address. 

An error in system 
initialization has caused the 
DMA buffer of the CWS Agent 
Service Process to fall outside 
the low-order 128k bytes of 
memory or on an odd-byte 
boundary . 

1FA9 Invalid card bit. 

An error has occurred in the 
Cluster Line Protocol Handle. 
Contact Convergent 
Technologies . 

1FAA Busy bit 10. 

An error has occurred in the 
Cluster Line Protocol Handle. 
Contact Convergent 
Technologies . 

IFAD Unrecoverable protocol failure 

detected by a cluster 
workstation . 

The cluster workstation has 
determined that the master 
workstation is no longer 
obeying proper protocol 
procedures. This can be caused 
by a hardware failure 
(including cabling) or 
excessive Multibus DMA loading. 

1FAF An error in the hardware (SIO 

or cabling) on the cluster line 
has caused a temporary 
inability of the cluster 
workstation to communicate with 
the master workstation. 


Status Codes A-37 



Hexa- 

Decimal decimal 
Value Value Meaning 


8112* 1FB0 Master workstation disconnect. 

An unrecoverable protocol 
failure has occurred at the 
master workstation and it has 
refused further communications 
with this workstation. The 
most likely cause is a dupli- 
cate workstation identification 
somewhere within the cluster 
(if so, the workstation with 
the duplicate identification 
should have simultaneously 
crashed with this error) . 

Other possible causes are the 
same as code 8109. 

8113 1FB1 Request block error. 

An improperly formatted request 
block was repeatedly sent by a 
workstation . 


8115 1FB3 


8116 1FB4 


8117 1FB5 


Bootstrap failure. 

A protocol failure occurred 
during the bootstrap process. 

No IDs. 

The ID search algorithm was 
unable to find a free ID. In 
general, this indicates that 
the system build performed for 
the Operating System currently 
running on the master work- 
station specified too few IDs 
for the cluster configuration. 

ID search failure. 

The ID search algorithm found a 
free ID but was unable to lock 
onto it for use. In general, 
this indicates a serious 
hardware or software problem. 


2780/3780 and 3270 

(See the 2780/3780 RJE Terminal Emulator Manual and the 3270 
Terminal Emulato~r~~ Manual for more information. ) 

8205 200D Host computer not polling. 
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8207 200F Invalid 3270 command. 

A subsystem error in the 3270 
emulator. Contact Convergent 
Technologies . 

8208 2010 Unexpected response. 

A subsystem error in the 3270 
emulator. Contact Convergent 
Technologies . 

8209 2011 Buffer too small. 

The buffer must be large enough 
to accept the longest EBCDIC 
transmission from the host 
computer, which may be larger 
than the screen size. 

8210 2012 Request from unknown 

workstation. 

0pen3270Emulator must be the 
first request issued, and the 
device address in all 
subsequent requests must match 
the one returned from 
0pen3 27 OEmula tor . 

8211 2013 Too many workstations. 

The number of device addresses 
already assigned is equal to 
the maximum set at system 
build; no further 
Open3270Emulator requests can 
be honored. 

8212 2014 Reject. 

Subsystem error in the 3270 
emulator. Contact Convergent 
Technologies . 

8213 2015 For 2780/3780: protocol 

failure during reception. 

For 3270: protocol failure 

after selection. 

A valid selection was received; 
however the normal BSC error 
recovery procedures were unable 
to successfully receive a data 
block from the host computer. 


Status Codes 


A-39 



Decimal 

Value 

Hexa- 

decimal 

Value 

Meaning 

8214 

2016 

For 2780/3780: protocol 

failure during transmission. 



For 3270: protocol failure 

after poll. 

A valid poll sequence was 
received; however the normal 
BSC error recovery procedures 
were unable to successfully 
transmit a data block to the 
host computer . 

8218 

201A 

Reverse interrupt received from 
host computer. 

Transmission was terminated. 

8219 

201B 

An attempt was made to sign on 
when already signed on, or sign 
off when already signed off or 
not idle. 

8220 

201C 

Invalid request code for RJE 
system service. 

8221 

201D 

Communications line 
disconnected . 

8222 

201E 

Cannot create sequenced file 
specification . 

The entire range of sequence 
numbers (0-65535) was tried. 

8223 

201F 

Invalid configuration file 
format . 

Use the Configure RJE command 
to create a properly formatted 
file . 

Communications Interrupt 

Handlers 


8400 

20D0 

Invalid line number. 

The line number specified in 
SetCommISR or ResetCommISR must 
be either 0 or 1 . 

8401 

20D1 

Line in use. 

The line specified in 
SetCommISR is being used by the 
Operating System. 
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Value Value Meaning 

X. 25 Packet Access Method 

8500 2134 Link level down. 

The link level of the X.25 
Network Gateway system service 
is not operational. This situ- 
ation occurs either at power up 
before communication with the 
PDN is established or during 
operation if an irrecoverable 
link level error occurs. The 
X.25 Network Gateway system 
service link level software 
should reestablish communica- 
tion as soon as possible. If 
the link level remains down for 
an extended period, an irrecov- 
erable error at the physical 
level or the link level exists, 
and a PDN representative should 
be contacted. 

8501 2135 Packet level down. 

The packet level of the X.25 
Network Gateway system service 
is not operational. This situ- 
ation occurs (1) at power up, 

(2) during operation following 
a link level failure and subse- 
quent reestablishment of link 
level communications, or (3) 
following an irrecoverable 
packet level error condition. 
The X.25 Network Gateway system 
service should reestablish the 
packet level as soon as possi- 
ble. If the packet level 
remains down for an extended 
period, a PDN representative 
should be contacted. 


Status Codes A-41 


Hexa- 

Decimal decimal 
Value Value Meaning 


8502 2136 Maximum number of this request 

has been queued. 

Previously submitted requests 
of this type must be completed 
before more can be issued. The 
maximum number of each request 
type i s 

o Notif yNextlncomingCal 1 

requests: the number of 

virtual circuits per line. 

o ReadX25Packet requests: 
two per virtual circuit. 

o WriteX25Packet requests: 
five per virtual circuit. 

o all other packet access 
method operation 
requests: one per virtual 

circuit . 

Generally, since the packet 
level should complete requests 
in a short period, the request 
should be resubmitted. If this 
condition persists, Query- 
X25Status should be used to 
examine the state of the X.25 
Network Gateway system service 
to determine the cause of the 
delay . 

8503 2137 X.25 Network Gateway system 

service is busy. 

Insufficient memory is availa- 
ble for the X.25 Network Gate- 
way system service to process 
any more requests at this 
time. In normal operation, the 
X.25 Network Gateway system 
service should complete enough 
requests to free the memory 
required for new requests. If 
this error persists, 
reinstallation of the X.25 
Network Gateway with additional 
memory should be considered. 
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8504 


8505 


8506 


8507 


8508 


8509 


Hexa- 

decimal 

Value Meaning 


2138 Process termination. 

All requests were (or shortly 
will be) returned and all vir- 
tual calls were (or shortly 
will be) cleared because the 
user's process has terminated. 

2139 Bad port parameter. 

A NotifyNextlncomingCall opera- 
tion contains a port range with 
one of two error conditions : 

o The high port number is 
less than the low port 
number . 

o The low and/or high port 
number is not in ASCII 
digits . 

213A No virtual circuit available. 

An InitiateX25Call operation 
was received, but all virtual 
circuits were either in use or 
out of order. 

213B User-specified time out. 

A ReadX25Packet or a Notify- 
NextlncomingCall operation 
could not be fulfilled by the 
packet level during the speci- 
fied maximum time. 

213C Virtual circuit in use. 

A request was received for a 
virtual circuit (or permanent 
virtual circuit) in use by some 
other user . 

213D Call collision. 

An incoming call was received 
on a virtual circuit before an 
InitiateX25Call operation that 
had been allocated to that 
virtual circuit could be com- 
pleted. The process should 
resubmit the InitiateX25Call 
operation. 


Status Codes A-43 



Hexa- 

Decimal decimal 

Value Value Meaning 

8510 213E Call cleared. 

An AcceptX25Call operation was 
made on a circuit for which no 
call was pending. 

8511 213F Virtual circuit not in use. 

A request was received for a 

virtual circuit (or permanent 
virtual cicuit) that was not 
allocated to any user. 

8512 2140 DTE clear. 

Either an erroneous packet was 
received from the PDN, or the 
process requested that the call 
be terminated. The X.25 Net- 
work Gateway system service 
cleared the call that was on 
this virtual circuit. Data in 
the process of being trans- 
ferred may have been lost. 

8513 2141 DCE clear. 

The PDN cleared the call that 
was on this virtual circuit. 
Data in the process of being 
transferred may have been lost. 

8514 2142 DTE reset. 

Either an erroneous packet was 
received from the PDN, or the 
process requested the call be 
reset. The X.25 Network Gate- 
way system service reset the 
call on this virtual circuit. 
Data in the process of being 
transferred may have been lost. 

8515 2143 DCE reset. 

The PDN reset the call on this 
virtual circuit. Data in the 
process of being transferred 
may have been lost. 
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8516 


8517 


8518 


8519 


8520 


Hexa- 

decimal 

Value Meaning 


2144 DTE restart. 

An erroneous packet was 
received from the PDN, and the 
X.25 Network Gateway system 
service was restarted. All 
active calls were cleared. 

Data in the process of being 
transferred may have been lost. 


2145 


2146 


2147 


2148 


DCE restart. 

The PDN restarted the packet 
level. All active calls were 
cleared. Data in the process 
of being transferred may have 
been lost. 

Virtual circuit not in data 
transfer mode. 

A read, write, reset, or inter- 
rupt request was received for a 
virtual circuit that was not in 
the correct state. Either no 
call was present, or the cir- 
cuit was in the process of 
being cleared or reset. 

Interrupt data. 

This indicates normal comple- 
tion of a read request, but 
with an interrupt data packet 
rather than a normal data 
packet. Interrupt data are 
returned to the process before 
any normal packets being held 
for the process by the packet 
level . 

Virtual circuit out of order. 

An irrecoverable error occurred 
on this virtual circuit, and 
the X.25 Network Gateway system 
service declared it out of 
order. All calls on this cir- 
cuit were cleared. The circuit 
can be restored only by the 
PDN. 


Status Codes 


A-45 


Decimal 

Hexa- 

decimal 


Value 

Value 

Meaning 

8521 

2149 

Internal time out. 

The PDN did not respond to the 
packet generated by the request 
in the required time period. 

The process should resubmit the 
request . 

8522 

214A 

Invalid virtual circuit number. 
Either (1) a request was 
received for a virtual circuit 
with a vch parameter that is 
either out of bounds or is 0 
(circuit 0 is reserved), or (2) 
a ConnectX25Permanent operation 
was received for a nonpermanent 
virtual circuit. 

8523 

214B 

Data truncated. 

Data to be returned to the 
process exceeded the size of 
sPacketRet as specified by the 
process. The data were 
truncated to the size of the 
buffer . 

8524 

214C 

No buffer. 

A read or write operation was 
attempted, with sBuffer equal 
to 0 . 

8525 

214D 

Permanent circuit. 
ClearX25Call or AcceptX25Call 
was issued with the vch 
parameter of a permanent 
virtual circuit. 

CommlOP 

8601 

2199 

CommlOP time out. 

The CommlOP failed to update 
the status cell within a 
certain time period. Run the 
CommlOP diagnostic to determine 
the cause of the error. 
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Decimal 

Value 


8602 


8603 


8604 


8605 


8606 


8607 


8610 


8615 


Hexa- 

decimal 

Value Meaning 


219A Line not configured. 

The communications line number 
is not currently configured in 
the system. Change the system 
build parameters . 

219B Missing system image for 

Comm I OP . 

The file [Sys] <Sys> CommlOP >Sys- 
Image.Sys was not found. 

219C CommlOP loading error. 

The CommlOP could not be loaded 
successfully. Run the CommlOP 
diagnostic . 

219D Invalid CommlOP data structure. 

There is an invalid queue 
entry, an invalid CommlOP 
number, etc. Take a crash dump 
and run the CommlOP diagnostic. 

219E CommlOP channel restart. 

The carrier problem on the 
CommlOP channel was cleared. 

219F CommlOP channel hold. 

There is a carrier problem on 
one of the CommlOP channels. 
Disconnect the CWSs one at a 
time to determine which is 
failing . 

21A2 CommlOP command failure. 

The CommlOP returned erroneous 
control information to the 
master workstation. 

21A7 Bad master workstation to 

CommlOP command . 

The CommlOP did not recognize 
the command from the master 
workstation . 


Status Codes A-47 



Decimal 

Value 

8616 

8617 

8618 

8621 

8622 

8623 

8624 
8631 


8632 


Hexa- 

decimal 

Value Meaning 


21A8 CommlOP bootstrap checksum 
failure . 

The CommlOP checksum test 
failed while loading its code 
file from the master 
workstation . 

21A9 CommlOP stacker/destacker 

failure . 

The Multibus interface hardware 
(stacker/destacker) on the 
CommlOP is not functional. 

21AA Bad CommlOP interrupt. 

The CommlOP received an 

interrupt from an unknown 
source . 

21 AD CommlOP RAM failure in 

write/read test. 

21AE CommlOP RAM failure - invalid 

bit set. 

21AF CommlOP failure - invalid bit 

cleared . 

21 BO CommlOP RAM failure in 

addressing test. 

21B7 CommlOP handler time out. 

The CommlOP did not get proper 
status information from the 
master workstation. The most 
probable cause is a software 
problem in the master 
workstation that caused the 
master workstation Agent 
Service Process to be 
permanently suspended. 

21B8 Invalid CommlOP check word. 

The CommlOP has encountered an 
invalid check word in its 
queues. There is probably a 
memory error in the master 
workstation. 
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Hexa- 

decimal 

Value 

Meaning 

8633 

21B9 

CommlOP RAM checksum error. 
The CommlOP 1 s RAM is probably 
faulty. Run the CommlOP 
diagnostic . 

8634 

21 BA 

Invalid queue entry. 

The CommlOP has discovered an 
invalid queue entry in its data 
queues. This is possibly a 
software error. 

8635 

2 IBB 

Invalid CommlOP buffer pointer. 
The CommlOP received an invalid 
memory address of a buffer. 

8636 

21BC 

CommlOP carrier problem. 

8637 

21BD 

CommlOP software inconsistency. 
This is probably a software 
error. A crash dump should be 
taken . 

8641 

21 Cl 

CommlOP timer failure. 

The timer hardware on the 
CommlOP failed the 
initialization tests. 

8642 

21C2 

CommlOP DMA failure. 

The DMA hardware on the CommlOP 
failed the initialization 
tests . 

8643 

21C3 

CommlOP SIO static test 
failure . 

The communications hardware on 
the CommlOP failed the static 
initialization test. 

8644 

21C4 

CommlOP SIO functional test 
failure . 

The communications hardware on 
the CommlOP failed the 
functional test. 

8701 

2 1FD 

CWS time out. 

The CWS did not respond in the 
allotted time period. 



Status Codes A-49 



Decimal 

Value 


8702 


8703 


8704- 

8712 


8699 


Hexa- 

decimal 

Value Meaning 


21FE CWS CRC error. 

An excessive number of CRC 
errors were encountered from 
the CWS. Run the 
communications and the CommlOP 
diagnostics . 

21FF CWS overrun error. 

The CWS sent too much data per 
buffer. Check the CWS/master 
workstation system build 
parameters . 

2200- Bad protocol errors. 

2208 These errors are probably due 

to (1) a reset or power down on 
the CWS or (2) a faulty CWS. 

21FB The cluster is too heavily 

loaded when the 
GetClusterStatus operation is 
invoked . 
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APPENDIX B: STANDARD CHARACTER SET 


Table B-l below describes the 256-entry character 
set used when the keyboard is in character mode, 
the standard encoding is in the Keyboard Encoding 
Table, and the standard font is in the font 
RAM. Table B-2 below shows the graphic 
representation of the characters of Table B-l. 


CODE Keys 


When the keyboard is in character mode, the two 
CODE keys are special kinds of SHIFT keys. If 
either or both is depressed when a non-SHIFT key 
is pressed, the high-order bit of the key is 
turned on. For example, CODE-A generates 
80h + 61h = OElh, CODE-space generates 
80h + 20h = OAOh, etc. Note that any of the 
values 80h...0FFh can be generated from the 
keyboard in this way. 

In addition, some of the character codes in the 
range 80h to ODFh have keyboard encodings that do 
not require the CODE key. 


Legend for Table B-l 

Uppercase alphabetics are used for the actual 
label on the key cap (for example, FINISH, 
SHIFT) . 

Lowercase alphabetics are used for descriptions 
of the key cap label (for example, left arrow) or 
video display character (for example, dagger). 

Where a character can be generated only by 
depressing a combination of SHIFT and/or CODE and 
another key, the key combination is shown as a 
hyphenated list of keys (for example, SHIFT-6). 

The four empty key posts covered by the double 
keys left-SHIFT, right-SHIFT, numeric-0, and NEXT 
are denoted by (SH-L 1 ), (SH-R 1 ), (O')/ and 
(NEXT' ) , respectively. 

The keys on the numeric pad are denoted "num 0" , 
etc. to distinguish them from the corresponding 
keys on the typewriter pad. 
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Table B-1. Standard Character Set (Page 1 of 8) 


Character 
Code 
(hexa- 
decimal ) 

Video Display 
Character 

Key 

00 

null 

HELP 

01 

up arrow 

up arrow 

02 

k (triangle) 

MARK 

03 

$ 

SHIFT-6 

04 

filled square 

FINISH 

05 

empty square 

PREV PAGE 

06 

1/2 

1/2 

07 

bell 

CANCEL 

08 

backspace 

BACKSPACE 

09 

tab 

TAB 

0A 

new line 

RETURN 

OB 

down arrow 

NEXT 

down arrow 

OC 

formfeed 

NEXT PAGE 

OD 

A (triangle) 

BOUND 

OE 

left arrow 

left arrow 

OF 

double dagger 

MOVE 

10 

1/4 

SHIFT-1/2 

11 

t 

SCROLL UP 

12 

right arrow 

right arrow 

13 

trough 

SCROLL DOWN 

14 

raised dot 

COPY 

15 

4- 

fl 

16 

I (vertical bar) 

f 2 

17 

§ 

f 3 

18 


f4 

19 

similarity 

f 5 

1A 

IT 

f 6 

IB 

filled circle 

GO 

1C 

not 

f 7 

ID 

4 

f 8 

IE 

4= 

f9 

IF 

A 

flO 

20 

space 

space 

21 

i 

SHIFT-1 

22 

It 

SHIFT- 1 

23 

# 

SHIFT-3 

24 

$ 

SHIFT-4 

25 

o. 

"o 

SHIFT-5 






Table B-1. Standard Character Set (Page 2 of 8) 

Character 
Code 
(hexa- 
decimal ) 

Video Display 
Character 

Key 

26 

& 

SHIFT-7 

27 

' (single quote) 

I 

28 

( 

SHIFT-9 

29 

) 

SHIFT-0 

2A 

* 

SHIFT-8 

2B 

+ 

SHIFT-= 

2C 

, ( comma ) 


2D 

- (hyphen) 


2E 

. (period) 

e 

2F 

/ 

/ 

30 

0 

0 

31 

1 

1 

32 

2 

2 

33 

3 

3 

34 

4 

4 

35 

5 

5 

36 

6 

6 

37 

7 

7 

38 

8 

8 

39 

9 

9 

3A 

o 

• 

SHIFT-; 

3B 

• 

i 

• 

3C 

< 

SHIFT-C 

3D 

= 

= 

3E 

> 

SHIFT-] 

3F 

? 

SHIFT-/ 

40 

@ 

SHIFT-2 

41 

A 

SHIFT-a 

42 

B 

SHIFT -b 

43 

C 

SHIFT-c 

44 

D 

SHIFT-d 

45 

E 

SHIFT-e 

46 

F 

SHIFT-f 

47 

G 

SHIFT-g 

48 

H 

SHIFT -h 

49 

I 

SHIFT-i 

4A 

J 

SHIFT-j 

4B 

K 

SHIFT-k 

4C 

L 

SHIFT-1 

4D 

M 

SHIFT-m 
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Table B-1. Standard Character Set (Page 3 of 8) 


Character 



Code 



(hexa- 

Video Display 


decimal ) 

Character 

Key 

4E 

N 

SHIFT-n 

4F 

0 

SHIFT-o 

50 

P 

SHIFT -p 

51 

Q 

SHIFT-q 

52 

R 

SHIFT-r 

53 

S 

SHIFT-s 

54 

T 

SHIFT-t 

55 

U 

SHIFT-U 

56 

V 

SHIFT-v 

57 

W 

SHIFT-W 

58 

X 

SHIFT-x 

59 

Y 

SHIFT-y 

5A 

Z 

SHIFT-Z 

5B 

[ 

C 

5C 

\ (back slash) 

SHIFT-num 8 

5D 

] 

] 

5E 

/\ (caret) 

/\ 

5F 

( underline) 

SHIFT — 

60 

x (reverse ac- 

SHIFT-num 1 


cent) 


61 

a 

a 

62 

b 

b 

63 

c 

c 

64 

d 

d 

65 

e 

e 

66 

f 

f 

67 

g 

g 

68 

h 

h 

69 

i 

i 

6A 

j 

j 

6B 

k 

k 

6C 

1 

1 

6D 

m 

m 

6E 

n 

n 

6F 

o 

o 

70 

P 

P 

71 

q 

q 

72 

r 

r 

73 

s 

s 

74 

t 

t 


B 
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Table B-1. Standard Character Set (Page 4 of 8) 


Character 


Code 

(hexa- 

decimal) 

Video Display 
Character 

Key 

75 

u 

u 

76 

V 

V 

77 

w 

w 

78 

X 

X 

79 

y 

y 

7A 


z 

7B 

1 

SHIFT-num 4 

7C 

i (broken verti- 
cal bar) 

SHIFT-num 7 

7D 

< 

SHIFT-num 5 

7E 

~ (tilde) 

SHIFT- /\ 

7F 

filled rectangle 

DELETE 

80 

null 

CODE-HELP 
(SH-L' ) 

81 

1 

CODE-up arrow 
SHIFT (SH-L’) 

82 

' 0 

CODE-MARK 
(SH-R' ) 

83 

' 1 

CODE-SHIFT-6 
SHIFT (SH-R') 

84 

1 2 

CODE-FINISH 
(O' ) 

85 

' 3 

CODE-PREV PAGE 
SHIFT (O') 

86 

U 

CODE-1 /2 
(NEXT’ ) 

87 

1 5 

CODE-CANCEL 
SHIFT (NEXT*) 

88 

6 

CODE -BACKS PACE 

89 

7 

CODE-TAB 

8A 

! 8 

CODE-RETURN 

CODE-NEXT 

8B 

' 9 

CODE-down arrow 

8C 

® (superscript) 

CODE-NEXT PAGE 

8D 

^ (superscript) 

CODE-BOUND 

8E 

2 (superscript) 

CODE-left arrow 
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Table B-1. Standard Character Set (Page 5 of 8) 

Character 


Code 



(hexa- 

Video Display 


decimal ) 

Character 

Key 

8F 

3 (superscript) 

CODE-MOVE 

90 

4 (superscript) 

CODE-SHIFT-1/2 

91 

(superscript) 

CODE-SCROLL UP 

92 

6 (superscript) 

CODE-right arrow 

93 

7 (superscript) 

CODE-SCROLL DOWN 

94 

8 (superscript) 

CODE-COPY 

95 

8 (superscript) 

CODE— f 1 

96 

q (subscript) 

CODE- f 2 

97 

3 (subscript) 

CODE-f 3 

98 

2 (subscript) 

CODE-f 4 

99 

3 (subscript) 

CODE— f 5 

9A 

4 (subscript) 

CODE— f 6 

9B 

5 (subscript) 

CODE-GO 

9C 

g (subscript) 

CODE-f 7 

9D 

7 (subscript) 

CODE— f 8 

9E 

8 (subscript) 

CODE-f 9 

9F 

9 (subscript) 

CODE-flO 

AO 

A circle 

CODE-space 

A1 

a circle 

CODE-SHIFT-1 

A2 

A umlaut 

CODE-SHIFT-’ 

A3 

a umlaut 

CODE-SHIFT-3 

A4 

0 umlaut 

CODE-SHIFT-4 

A5 

o umlaut 

CODE-SHIFT-5 

A6 

0 slashed 

CODE-SHIFT-7 

A7 

o slashed 

CODE- ' 

A8 

U umlaut 

CODE-SHIFT-9 

A9 

u. umlaut 

CODE— SHIFT— 0 

AA 

c cedilla 

CODE-SHIFT-8 

AB 

e circumflex 

CODE-SHIFT— = 

AC 

e grave 

CODE-, 

AD 

e acute 

CODE — 

AE 

AE ligature 

CODE-. 

AF 

ae ligature 

CODE-/ 

BO 

0 

CODE— 0 

B1 

£ 

CODE-1 

B2 

degree 

CODE- 2 
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Table B-1. Standard Character Set (Page 6 of 8) 


Character 


Code 

(hexa- 

decimal) 

Video Display 
Character 

Key 

B3 

© 



CODE-3 

B4 

® 



CODE-4 

B5 

in 



CODE- 5 

B6 

I 



CODE-6 

B7 

' 1 



CODE- 7 

B8 

1 2 



CODE-8 

B9 

1 3 



CODE-9 

BA 

1 4 



CODE-SHIFT-; 

BB 

1 5 



CODE-; 

BC 

1 6 



CODE-SHIFT-[ 

BD 

1 7 



CODE-= 

BE 

1 8 



CODE-SHIFT-] 

BF 

1 9 



CODE-SHIFT-/ 

CO 

see 

Table 

B-2 

CODE-SHIFT-2 





SHIFT-HELP 

Cl 

see 

Table 

B-2 

CODE-SHIFT-a 





SHIFT-up arrow 

C2 

see 

Table 

B-2 

CODE-SHIFT-b 





SHIFT-MARK 

C3 

see 

Table 

B-2 

CODE-SHIFT-c 





SHIFT-BOUND 

C4 

see 

Table 

B-2 

CODE-SHIFT-d 





SHIFT-FINISH 

C5 

see 

Table 

B-2 

CODE-SHIFT-e 





SHIFT-PREV PAGE 

C6 

see 

Table 

B-2 

CODE-SHIFT-f 

C7 

see 

Table 

B-2 

CODE-SHIFT-g 





SHIFT-CANCEL 

C8 

see 

Table 

B-2 

CODE-SHIFT-h 





SHIFT-DELETE 

C9 

see 

Table 

B-2 

CODE-SHIFT-i 





SHIFT-GO 

CA 

see 

Table 

B-2 

CODE-SHIFT- j 





SHIFT-f 9 

CB 

see 

Table 

CO 

! 

to 

CODE-SHIFT-k 





SHIFT-down arrow 

CC 

see 

Table 

B-2 

CODE-SHIFT-1 





SHIFT-NEXT PAGE 

CD 

see 

Table 

B-2 

CODE-SHIFT-m 
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Table B-1. Standard Character Set (Page 7 of 8) 


Character 


Code 
(hexa- 
decimal ) 

Video Display 
Character 

Key 

CE 

see 

Table 

B-2 

CODE-SHIFT-n 
SHIFT-left arrow 

CF 

see 

Table 

B— 2 

CODE-SHIFT-o 

SHIFT-MOVE 

DO 

see 

Table 

B-2 

CODE-SHIFT-p 

OVERTYPE 

D1 

see 

Table 

B-2 

CODE-SHIFT-q 
SHIFT-SCROLL UP 

D2 

see 

Table 

B-2 

CODE-SHIFT-r 
SHIFT-right arrow 

D3 

see 

Table 

B-2 

CODE-SHIFT-s 
SHIFT-SCROLL DOWN 

D4 

see 

Table 

B-2 

CODE-SHIFT-t 

SHIFT-COPY 

D5 

see 

Table 

B-2 

CODE-SHIFT-U 
SHIFT— fl 

D6 

see 

Table 

B-2 

CODE-SHIFT-v 
SHIFT-f 2 

D7 

see 

Table 

B-2 

CODE-SHIFT -w 
SHIFT— f 3 

D8 

see 

Table 

B-2 

CODE-SHIFT-x 
SHIFT— f 4 

D9 

see 

Table 

B-2 

CODE-SHIFT-y 
SHIFT-f 5 

DA 

see 

Table 

B-2 

CODE-SHIFT-Z 
SHIFT— f 6 

DB 

see 

Table 

B-2 

CODE-C 

DC 

see 

Table 

B-2 

CODE-SHIFT-num 8 
SHIFT-f 7 

DD 

see 

Table 

B-2 

CODE-] 
SHIFT— f 8 

DE 

see 

Table 

B-2 

CODE- /\ 

DF 

see 

Table 

B-2 

CODE-SHIFT — 
SHIFT-flO 

EO 

see 

Table 

B-2 

CODE-SHIFT-num 1 

El 

see 

Table 

B-2 

CODE-a 

E2 

see 

Table 

B-2 

CODE-b 

E3 

see 

Table 

B-2 

CODE-c 

E4 

see 

Table 

B-2 

CODE-d 

E5 

see 

Table 

B-2 

CODE-e 
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Table B-1. Standard Character Set (Page 8 of 8) 


Character 
Code 
(hexa- 
decimal ) 

Video Display 
Character 

Key 


E6 

see Table 

B-2 

CODE-f 


E7 

see Table 

B-2 

CODE-g 


E8 

see Table 

B-2 

CODE-h 


E9 

see Table 

B-2 

CODE-i 


EA 

see Table 

B-2 

CODE-j 


EB 

see Table 

B-2 

CODE-k 


EC 

see Table 

B-2 

CODE-1 


ED 

see Table 

B-2 

CODE-m 


EE 

see Table 

B-2 

CODE-n 


EF 

see Table 

B-2 

CODE-o 


FO 

see Table 

B-2 

CODE-p 


FI 

see Table 

B-2 

CODE-q 


F2 

see Table 

B-2 

CODE-r 


F3 

see Table 

B-2 

CODE-S 


F4 

see Table 

B-2 

CODE-t 


F5 

see Table 

B-2 

CODE-u 


F6 

see Table 

B-2 

CODE-v 


F7 

see Table 

B-2 

CODE-w 


F8 

see Table 

B-2 

CODE-x 


F9 

see Table 

B-2 

CODE-y 


FA 

see Table 

B-2 

CODE-z 


FB 

see Table 

B-2 

CODE-SHIFT-num 

4 

FC 

see Table 

B-2 

CODE-SHIFT-num 

7 

FD 

bar chart 


CODE-SHIFT-num 

5 

FE 

FF 

bar chart 
bar chart 


CODE-S HIFT-/\ 
CODE-DELETE 
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Table B-2. Graphic Representation of the Standard Character Set. 


Video 

Display 

Character 

^ u-r- rr= -* -1 »- w- 1 >- r-ii 1*^1 ■■■ 

Character 

Code 

(hexa- 

decimal) 


Video 

Display 

Character 


Character 

Code 

(hexa- 

decimal) 


x— 

„ « 
S -2 « 


Character 

Code 

(hexa- 

decimal) 


Video 

Display 

Character 


Character 

Code 

(hexa- 

decimal) 


Video 

Display 

Character 

- «i ja ox> d> '+- cn x: ^ — e c o a cr l « 3 > 3 x >. n i m 

Character 

Code 

(hexa- 

decimal) 

§ESSSlS8lB$$gggSSiSN^^f?P:fSS^^Kfc 

Video 

Display 

Character 

8 «0D^0lH^JrZ0 [ L 0 ^h^ 3 X>NuXn< | 

Character 

Code 

(hexa- 

decimal) 


k_ 

S -2 O 
“5 

- = * W X 06 - * + - 1 '^OT-Cjnd-lTUDNOOO) .. -v»A^ 

Character 

Code 

(hexa- 

decimall 


Video 

Display 

Character 

j •!•-«» H «•■• r >*■ -H ^ 

Character 

Code 

(hexa- 

decimal) 

o-cvin^icifflNooro<moQuj^o^wn5;in®Nmo)<mooiiiu ; 

OCDOOOOOOOOOOOOOOT-1— -r-f— -r— T-T— T-T- 
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APPENDIX C: KEYBOARD CODES 


The keyboard codes generated by the 8048 keyboard 
microprocessor are shown in Table C-l below. 


Legend for Table C-l 

Uppercase alphabetics are used for the actual 
label on the key cap (for example, FINISH, 
SHIFT). 

Lowercase alphabetics are used for descriptions 
of the label (for example, left arrow). 

The four empty key posts covered by the double 
keys left-SHIFT, right-SHIFT, numeric-0, and NEXT 
are denoted by (SH-L'), (SH-R 1 ), (O'), and 
(NEXT'), respectively. 

The keys on the numeric pad are denoted "num 0", 
etc. to distinguish them from the corresponding 
keys on the typewriter pad. 


Keyboard Codes 
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Table C-1. Keyboard Codes Generated by an Unencoded Keyboard. 

(Page 1 of 2) 

Keyboard Code 
(hexadecimal ) 

Key 

00 

HELP 

01 

up arrow 

02 

MARK 

03 

BOUND 

04 

FINISH 

05 

PREV PAGE 

06 

1/2 

07 

CANCEL 

08 

BACKSPACE 

09 

TAB 

0A 

RETURN 

0B 

down arrow 

OC 

NEXT PAGE 

0D 

NEXT 

0E 

left arrow 

OF 

right arrow 

10 

(SH-L* ) 

11 

SCROLL UP 

12 

MOVE 

13 

SCROLL DOWN 

14 

COPY 

15 

fl 

16 

f 2 

17 

f 3 

18 

f 4 

19 

f 5 

1A 

f 6 

IB 

GO 

1C 

f 7 

ID 

f 8 

IE 

f 9 

IF 

flO 

20 

space 

21 

num 9 

22 

(SH-R 1 ) 

23 

(O' ) 

24 

( NEXT ' ) 

25 

unused code 

26 

unused code 

27 

1 (single quote) 

28 

unused code 

29 

unused code 
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Table C-1. Keyboard Codes Generated by an Unencoded Keyboard. 

(Page 2 of 2) 


Keyboard Code 
(hexadecimal ) 


2A 

unused code 

2B 

= 

2C 

, ( comma ) 

2D 

- (hyphen) 

2E 

. (period) 

2F 

/ 

. • .39 

0. . .9 

3A 

unused code 

3B 

i 

3C 

unused code 

3D 

unused code 

3E 

unused code 

3F 

invalid code 

40 

indicates tl 
released; al^ 
bit on (that 

41 

num 6 

42 

num - 

43 

ACTION 

44 

OVERTYPE 

45 

LOCK 

46 

num 2 

47 

num 3 

48 

left SHIFT 

49 

right SHIFT 

4A 

num 0 

4B 

num . 

4C 

left CODE 

4D 

right CODE 

. . 5A 

unused code 

5B 

[ 

5C 

num 7 

5D 

] 

5E 

/\ (caret) 

5F 

unused code 

60 

num 1 

. . 7A 

d. • • • Z 

7B 

num 4 

7C 

num 8 

7D 

num 5 

7E 

unused code 

7F 

DELETE 
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APPENDIX D: REQUEST CODES IN NUMERIC SEQUENCE 


Convergent Technologies has reserved the request 
codes listed here through 7FFFh for future 
expansion; they should not be used by system 
builders. Request codes 8000h-0FFFFh are 
available for system builder use. 

Request Code Operation Name 


00 

01 

02 

03 

04 

05 

06 

07 

08 

09 

10 
11 
12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 


( illegal ) 

SetPath 

ClearPath 

SetPref ix 

OpenFile 

CreateFile 

DeleteFile 

RenameFile 

GetFileStatus 

SetFileStatus 

CloseFile 

MountVolume 

DismountVolume 

ChangeFileLength 

GetDateTime 

GetVHB 

SetDevParams 

CreateDir 

DeleteDir 

CloseAllFiles 

QuietIO (internal) 

QueryVidHdw 

LoadFontRam 

LoadStyleRam 

LoadCursorRam 

ReadDir Sector 

( reserved) 

GetUCB 

Chain 

LoadTask 

SetFhLongevity 

GetFh Longevity 

ResetSubsys (internal) 

( reserved) 

( reserved ) 

Read 

Write 

ReadldAndData (internal) 
Format 
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Request Code Operation Name 


39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
61 
62 

63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 


DeviceReadld (internal) 

AllocExch 

DeallocExch 

AllocMemorySL 

DeallocMemorySL 

A1 locMemoryLL 

Deal locMemoryLL 

AllocAllMemorySL 

Re s e t Memo r y LL 

Que r y MemAva i 1 

OpenRTClock 

CloseRTClock 

SetDateTime 

Beep 

ReadKbd 

ReadKbdDirect 

QueryKbdLeds 

SetKbdLed 

SetKbdUnencodedMode 
Query KbdState 
Se tSys InMode 
ReadActionCode 
QueryWSNum 
CloseAllFilesLL 
KbdWakeUp (internal) 

BeeperOff (internal) 

SetKbdUnencodedModeReal ( internal ) 

KbdResetSysIn (internal) 

DisableActionFinish 

CheckpointSys In 

SetlntHandler 

ResetKbd (internal) 

ResetSysIn (internal) 

ResetAgent (internal) 

(reserved) 

ResetVideo 

InitVidFrame 

InitCharMap 

SetScreenVidAttr 

CloselSAM 

CreatelSAM 

DeletelSAM 

DeletelSAMRecord 

GetlSAMRecords 

LockISAM 

Modi f y IS AMRecord 

Open I SAM 

ReadlSAMRecordByUri 
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Request Code Operation Name 


87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 

103 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 

134 

135 

136 


ReadNextISAMRecord 

ReadUniquelSAMRecord 

Rename ISAM 

SetlSAMProtection 

SetupISAMIterationKey 

SetupISAMIterationPref ix 

SetupISAMIterationRange 

StorelSAMRecord 

UnlockISAM 

PurgelSAMUser (internal) 

OpenFileLL 

ConvertToSys 

ServeRq 

GetClusterStatus 
SetCommISR 
ResetCommISR 
KbAttn3270 (internal) 
ScreenRead3270 (internal) 
StatusRead3270 (internal) 
ReadyForCmd3270 (internal) 
StartEm3270 (internal) 
StopEm3270 (internal) 
CancelRq3270 (internal) 
ReportStatus3270 (internal) 
SetVerifyCode (internal) 
(reserved) 

(reserved) 

(reserved) 

( reserved) 

( reserved) 

(reserved) 

(reserved) 

(reserved) 

( reserved) 

SetLpISR 

DisableCluster 

GetRunFileHdr (internal) 

QueryDCB 

WriteLog 

SetCommISRRaw ( internal ) 

PurgelSAMTransaction 

EndlSAMTransaction 

GetlSAMRecordsHold 

HoldlSAMRecord 

ReadlSAMRecordByUriHold 

ReadNextISAMRecordHold 

ReadUniquelSAMRecordHold 

ReleaselSAMRecord 

SetupISAMIteration 

StartlSAMTransaction 
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Request Code Operation Name 


137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161 
162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 


AddQueueEntry 

RemoveKeyedQueueEntry 

ReadNextQueueEntry | 

ReadKeyedQueueEntry 

MarkNextQueueEntry 

MarkKeyedQueueEntry 

RemoveMarkedQueueEntry 

UnmarkQueueEntry 

RewriteMarkedQueueEntry 

Es tabli shQueueServer 

TerminateQueueServer 

PurgeQueueServer (internal) 

SignOf fRJE 
SignOnRJE 
StatusRJE 
Accept CommCal 1 
CloseAllCommLines 
CloseCommLine 
Dial Comm 
Disconnect Comm 
FlushCommBuf f er 
GetCommParameters 
OpenCommLine 
Re ad Comm 

SetCommParameters 

WriteComm 

BreakComm 

(reserved) 

NotifyNextlncomingCall 

Acc ep tX2 5 Cal 1 

InitiateX25Call 

ClearX25Call 

PurgeX25User 

ReadX2 5Packet 

WriteX25Packet 

WriteX25Interrupt 

ResetX25Call 

QueryX25Status 

ConnectX25Permanent 

RemovePartition 

GetPartitionHandle 

LoadPrimaryTask 

TerminatePartitionTasks 

VacatePartition 

CreatePartition 

SetPartitionLock 

SetPartitionExchange 

GetPartitionExchange 

GetPartitionStatus 

SetExitRunFile 
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Request Code Operation Name 


187 

188 

189 

190 

191 

192 

193 

194 

195 

196 

197 

198 

199 

200 
201 
202 
203 


QueryExitRunFile 

Conf igureSpooler 

SpoolerPas sword 

Ope nT ape 

ReadTapeRecords 

WriteTapeRecords 

TapeOperation 

CloseTape 

PurgeTapeUser 

TapeStatus 

ResetSplr (internal) 

Modi f y ISAMRecordByKey 
DeletelSAMRecordByKey 
LogRemote (internal) 
VacateParCleanup (internal) 
GetWSUserName 
SetWSUserName 
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APPENDIX E: DATA STRUCTURES 


This appendix describes the following: 

o System Common Address Table 

o Application partition and batch 

structures including 

Batch Control Block 
Extended Partition Descriptor 
Extended User Control Block 
Partition Configuration Block 
Partition Descriptor 

o System Configuration Block 


data 
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SYSTEM COMMON ADDRESS TABLE 


The System Common Address Table (SCAT) contains 
the 4-byte logical memory address of each of a 
number of system data structures. A field whose 
name begins with "po" contains the logical memory 
address of the offset (from DGroup of the System 
Image) of the system data structure rather than 
the memory address of the system data structure 
itself. The SCAT, shown in Table E-l below, 
begins at memory location 240h. 


Table E-1. System Common Address Table. (Page 1 of 5) 

Memory 

Location 

Field 

Description 

240h 

pSysTime 

System date/time 
structure . 

24 2h 

saDGroup 

Segment base address of 
the DGroup of the System 
Image (1-word field; 
overlaps second half of 
pSysTime) . 

244h 

pVCB 

Video Control Block. 

248h 

pRgSysError 

System Error Status 
Block. 

24Ch 

ppPcbRun 

Memory address of the 
Process Control Block of 
the currently running 
process . 

250h 

pASCB 

Application System 
Control Block. 

254h 

pVersion 

Version is a character 
string whose length is 
defined by its own first 
byte . 
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Table E-1. System Common Address Table. (Page 2 of 5) 


Memory 

Location 

Field 

Description 

258h 

prgpCISR 

Array of entry points 
(CS:IPs) of the 
Communications Interrupt 
Service Routines . 

2 5Ch 

prgQDsCISR 

Array of 4-byte 
entries. The second two 
bytes of each entry are 
the segment base address 
to load into the DS 
Register when the 
corresponding CISR is 
activated. The first two 
bytes are unused. 

2 6 Oh 

pDefaultCISR 

First instruction of 
default CISR. 


264h pcLinkBlks Word containing the count 

of available link blocks. 


268h pLinkBlkAvail 

First link block on a 
linked list of link 
blocks available. 

26Ch pcLinkBlkRes 

Word containing the count 
of reserved link 
blocks. This is the sum 
of link blocks reserved 
at system build for the 
PSend primitive and those 
dynamically reserved by 
the Request primitive for 
use by the Respond 
primitive . 

2 7 Oh prgKbdEncode 

Keyboard Encoding Table 
(the default contents are 
shown in Appendix B) . 
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Table E-1. System Common Address Table. (Page 3 of 5) 

Memory 

Location 

Field 

Description 

274h 

poRgExch 

Offset to exchange zero. 

278h 

poRgLinkBlk 

Offset to the first link 
block. 

27Ch 

poRgODcb 

Offset to the first entry 
in the array of offsets 
to the Device Control 
Blocks . 

280h 

poRgOFcb 

Offset to the first entry 
in the array of offsets 
to the File Control 
Blocks . 

284h 

poRgOUcb 

Offset to the first entry 
in the array of offsets 
to the User Control 
Blocks . 

28 8h 

poRgOVhb 

Offset to the first entry 
in the array of offsets 
to the Volume Home 
Blocks . 

28Ch 

poRgPcb 

Offset to the first 
Process Control Block. 

290h 

poRgPTrb 

Offset to the first entry 
in the array of memory 
addresses of active timer 
request blocks . 

294h 

pSSET 

System Service Exchange 
Table (the Service 
Exchange Table for 
request codes 0-7FFFh) . 
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Table E-1. System Common Address Table. (Page 4 of 5) 


Memory 

Location 

Field 

Description 

298h 

pUSET 

User Service Exchange 
Table (the Service 
Exchange Table for 
request codes 8000h- 
OFFFFh) . 

29Ch 

pRunQ 

Queue of ready-to-run 
Process Control Blocks. 

2B4h 

pBootBlock 

A 16-word array that 
contains the information 
passed to the OS by the 


bootstrap ROM. 

2B8h pBootDevName 

Character string 
containing the name of 
the device from which the 
OS was bootstrapped. The 
first byte of the string 
contains the byte count 
of the string. 

2BCh pCrashDumpDevName 

Character string 
containing the name of 
the device to which the 
CTOS crash dump was 
written. The first byte 
of the string contains 
the byte count of the 
string . 

2C0h pHdcCntlBlk 

Hard Disk (Winchester) 
Control Block. 

2C4h pFloppyCntlBlk 

Floppy Disk Control 
Block . 
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Table E-1. System Common Address Table. (Page 5 of 5) 

Memory 

Location 

Field 

Description 

2C8h 

pConf igBlk 

System Configuration 
Block . 

2D4 

pSysDeviceNum 

System device number. 

2D8 

pSLSC 

System Local Service Code 
Table (that is, the Local 
Service Code Table for 
request codes 0-7FFFh) . 

2 DC 

pULSC 

User Local Service Code 
Table (that is, the Local 
Service Code Table for 
request codes 8000h- 
OFFFFh ) . 

2E4 

pExtCntlReg 

A byte that is a copy of 
the contents of the 
external control register 
on AWS-210, -220, and 
-230 workstation hardware 
(AWS-210, -220, and -230 
workstations only) . 

2E8 

pGrPortVal 

The last byte written to 
the graphics Multibus 
port . 

2 EC 

pFontRamBuf 

The pointer to the 8k 
buffer in the Operating 
System for LoadFontRam 
operation. It is set to 
0 if there is no buffer 
reserved ( IWS work- 
stations only) . 
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APPLICATION PARTITION AND BATCH DATA STRUCTURES 

The application partition and batch data 
structures are located in each application 
partition. They provide information about the 
application system executing in an application 
partition. 

The application partition data structures are: 

o Application System Control Block (described 
in the "Parameter Management" section), 

o Extended Partition Descriptor, 

o Extended User Control Block, 

o Partition Configuration Block, and 

o Partition Descriptor. 

The batch data structure is: 

o Batch Control Block. 

The Batch Control Block contains the job name, 
the batch queue name, the file handle and logical 
file address of the batch job control file, the 
Sysln and SysOut byte stream work area and 
buffers, and information on assigned devices. 
Its format is shown in Table E-2 below. 


Data Structures 


E-7 




Table E-2. Batch Control Block. 

Offset 

Field 

Size 
(bytes ) 

0 

SysInBuf fer 

512 

512 

SysOutBuf fer 

512 

1024 

cbJobName 

1 

1025 

JobName 

12 

1037 

cbQueueName 

1 

1038 

QueueName 

50 

1088 

f SysInBsOpen 

1 

1089 

SysInBswa 

50 

1139 

f SysOutBsOpen 

1 

1140 

SysOutBswa 

51 

1191 

fhLogLL 

2 

1193 

lfaLogLL 

4 

1197 

cAssDev 

2 

1199 

cbLogicalDevl 

1 

1200 

LogicalDevl 

12 

1212 

cbLogicalDev2 

1 

1213 

LogicalDev2 

12 

1225 

cbLogicalDev3 

1 

1226 

LogicalDev3 

12 

1238 

cb Physical Devi 

1 

1239 

PhysicalDevl 

78 

1317 

cbPhysicalDev2 

1 

1318 

PhysicalDev2 

78 

1396 

cbPhysicalDev3 

1 

1397 

PhysicalDev3 

78 

1475 

qeh 

4 

1479 

qehStatus 

4 

1483 

bSequence 

1 

1484 

f SpoolSysOut 

1 

1485 

dateTime 

4 


The Extended Partition Descriptor contains 
specifications for the current application file 
and exit run file. Its format is shown in Table 
E-3 below. 

The Extended User Control Block contains 
information including the offset of the Partition 
Descriptor and the exit status code. Its use is 
transparent to the user. 
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Table E-3. Extended Partition Descriptor. 



Size 

Offset 

Field 

(bytes ) 

0 

cbCurrentRunFileSpec 

1 

1 

CurrentRunFileSpec 

78 

79 

cbExitRunFileSpec 

1 

80 

ExitRunFileSpec 

78 

.158 

cbExitRunFilePswd 

1 

159 

ExitRunFilePswd 

12 

171 

ExitRunFilePriority 

1 

The Partition Configuration 

Block contains the 

offsets 

of the Extended Partition Descriptor, 

Batch 

Control Block, and 

Application System 

Control 

Block. Its format is 

shown in Table E-4 

below. 



Table E-4. Partition Configuration Block. 



Size 

Offset 

Field 

(bytes ) 

0 

oExtendedParDesc 

2 

2 

oBCB 

2 

4 

oASCB 

2 


The Partition Descriptor contains the partition 
name, the boundaries of the partition and of its 
long- and short-lived memory areas, and internal 
links to Partition Decriptors in other parti- 
tions. Its format is shown in Table E-5 below. 
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Table E-5. Partition Descriptor. 


Offset 

Field 

Size 
(bytes ) 

0 

oForwardLink 

2 

2 

oBackwardLink 

2 

4 

saLowBound 

2 

6 

saMinLL 

2 

8 

saCurLL 

2 

10 

saCurSL 

2 

12 

saMaxSL 

2 

14 

saHighBound 

2 

16 

cbPartitionName 

1 

17 

PartitionName 

12 

29 

fPartitionVacant 

1 

30 

fPartitionLocked 

1 

31 

PartitionExchange 

2 


The location of the data structures in the 
application partition are shown in Figure E— 1 
below. For more information, see the 
"Application Partition Management" section. 


E— 10 


CTOS* Operating System Manual 


5/82 





Figure E-1. Appiication Partition and Batch Data Structures. 
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SYSTEM CONFIGURATION BLOCK 


The System Configuration Block contains detailed 
information about the CTOS System Image 
(workstation configuration and system build 
parameters). The System Configuration Block is 
located in the system partition. Its address is 
recorded at address 2C8h in the System Common 
Address Table. 

The format of the System Configuration Block is 
shown in Table E-6 below. 


Table E-6. System Configuration Block (Page 1 of 3) 

Offset 

Field 

Size 
(bytes ) 

Description 

0 

Sys tem- 
BuildType 

1 

Type of system build 
(used internally) . 

1 

Os Type 

1 

Type of Operating 
System : 

0 swapping; 

1 resident. 

2 

SaMinLL 

2 

Segment base address 
of first byte of 
long-lived memory. 

4 

SaCurrLL 

2 

Segment base address 
of first byte of the 
common pool of 
memory . 

6 

SaCurrSL 

2 

Segment base address 
of first byte above 
common pool of 
memory . 

8 

SaMaxSL 

2 

Segment base address 
of first byte above 
short-lived memory. 
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Table E-6. System Configuration Block. (Page 2 of 3) 


Size 

Offset Field (bytes) Description 


10 SaMemMax 2 


12 cPcb 2 

14 cExch 2 

16 cLinkBlk 2 

18 cLinkBlkRes 2 


20 cTrb 2 

22 clob 2 

24 cFcb 2 

26 cVhb 2 

28 cUcb 2 

30 cUfb 2 


32 HardwareType 1 


Segment base address 
of first byte above 
installed system 
memory . 

Number of Process 
Control Blocks. 

Number of exchanges. 

Number of link 
blocks . 

Number of reserved 
link blocks. 

Number of timer 
request blocks. 

Number of i/o 
Blocks . 

Number of File 
Control Blocks . 

Number of Volume 

Home 

Blocks . 

Number of User 
Control Blocks. 

Number of User File 
Blocks . 

Workstation model: 

0 IWS ; 

1 AWS-210; 

2 AWS-220, -230; 

3 AWS-240 . 
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Table E-6. System Configuration Block. (Page 3 of 3) 

Offset 

Field 

Size 

(bytes) 

Description 

33 

Cluster- 

Configura- 

tion 

1 

Type of 
configuration : 

0 Standalone; 

1 Cluster; 

2 Master. 

34 

fNoFile- 

System 

1 

Local file system or 
not : 

0 With file 
system; 

1 Without file 
system. 

35 

f Comm I op 

1 

CommlOP or not: 

0 Without 
CommlOP ; 

1 With CommlOP . 

36 

fMultiparti- 1 
tion 

Multiple application 
partitions or not: 

0 Single 
application 
partition; 

1 Multiple 
application 
partitions . 
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APPENDIX F: ACCESSING CTOS OPERATIONS FROM ASSEMBLY LANGUAGE 


This Appendix describes (1) accessing CTOS 
operations from programs written in assembly 
language and (2) the Convergent conventions for 
argument-passing, register usage, and segments, 
classes, and groups. Assembly language examples 
illustrate both CTOS access and the conventions. 


Argument Passing 


The Operating System and object module procedures 
(such as byte streams) deal with data items and 
structures of many different sizes ranging from 
single-byte items, such as Boolean flags, to 
multibyte structures, such as request blocks and 
Byte Stream Work Areas. 

Three of these are special: 1-byte, 2-byte, and 
4-byte data items. Only these are passed as 
arguments on the stack or returned as results in 
the registers. 

When it is necessary to pass a data structure as 
an argument, the 4-byte logical memory address of 
(pointer to) the data structure is used as the 
argument . 

Note that pointers are arranged in memory with 
the low-order part, the offset, at the lower 
memory address and the high-order part, the 
segment base, at the higher memory address. 
However, the processor architecture of the 
Convergent Information Processing System is such 
that stacks grow from high memory addresses 
toward low memory addresses. Hence, the high- 
order part of a pointer is pushed before the low- 
order part. 

Also note that byte arguments are pushed on to 
the stack as words, with the low-order byte of 
the word being the argument. 

If the argument is Boolean, the convention is to 
use a byte value of OFFh for true and 0 for 
false. This is not simply nonzero or 0, since 
the actual test used is to see if the least 
significant bit is set or clear. 
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Register Usage 


The contents of registers CS, DS, SS, SP, and BP 
are preserved across calls: they are the same on 
the return as they were just prior to the pushing 
of the first argument on to the stack. It is 
assumed that SS and SP point, respectively, to 
the base of the stack and the top of the stack, 
and this stack is used, in general, by the called 
service. None of the other registers or the 
flags are preserved across calls. 

If the procedure called is a function (that is, 
if it returns a value), the return value is 
placed in registers according to the type of 
value . 

If the value is a byte, it is returned in AL (the 
low byte of register AX) . 

If the value is a word (two bytes), it is 
returned in AX (most of the object module 
procedures return a value of type ErcType, which 
is actually a word). 

If the value is a doubleword (a pointer or a 
logical file address), the most significant word 
(or segment part of a pointer) is returned in ES 
and the least significant word (or offset of a 
pointer) is returned in BX. 


BP Register 


The above conventions place no particular 
requirement on the contents of BP. However, the 
Convergent Debugger cannot trace the stack of a 
procedure being debugged if BP is not used 
according to one of the two Convergent BP usages. 

The most common usage uses BP as a pointer to the 
stack just below the local variable memory that 
is placed on the stack. All references to 
arguments and local variables are then made using 
BP. Each procedure has a prologue and an 
epilogue that look like: 
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SUB 

SP, 

sLocalFrame 

PUSH 

BP 


MOV 

• 

BP, 

SP 

• 

• 

POP 

BP 


RET 

sArgumentFrame 


The values, for sLocalFrame and sArgumentFrame are 
always even. sLocalFrame is the number of bytes 
of local variables, and s Argument frame is the 
number of bytes pushed on to the stack by the 
calling service (each PUSH instruction adds two 
bytes ) . 

Convergent Pascal and FORTRAN have an alternative 
BP usage. BP points to the top of the arguments 
and local variables ( sReturnAddress is two if the 
procedure is NEAR and four if it is FAR) : 

PUSH BP 

MOV BP, SP 

SUB SP, sLocalFrame 

ADD BP, sArgumentFrame + sReturnAddress 


ADD SP, sLocalFrame 

POP BP 

RET sArgumentFrame 


Segments, Classes, and Groups 

Object module procedures assume that the 
registers SS and DS are set to DGroup. This is 
done automatically for a Pascal or FORTRAN main 
program. However, an assembly language main 
program must explicitly set the registers. The 
program should include something similar to the 
following : 

EXTRN Exit 
PUBLIC Main 

Stack SEGMENT STACK 'Stack' 

DB sStack DUP (?) 
raStackLim LABEL BYTE 
Stack ENDS 

DGroup GROUP Stack 
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YourCode SEGMENT 
ASSUME CS: YourCode 
Main PROC FAR 


MOV 

AX, 

DGroup 

MOV 

DS, 

AX 

MOV 

SS, 

AX 

MOV 

SP, 

OFFSET DGroup :raStackLim 


CALL Exit 
Main ENDP 
YourCode ENDS 
END Main 

The segments included in the group DGroup are: 


Segment 

Class 

Const 

Const 

Statics 

Const 

Data 

Data 

Stack 

Stack 

Memory 

Memory 


Example 1 


The TypeSector program copies the first sector of 
a file to the video display, using CTOS file 
system operations to open and read the file and 
SAM (the Sequential Access Method) to write to 
the video display. The file specification used 
is obtained from the Executive. The program 
assumes the file name is specified in a form 
like : 

Command TypeSector 

TypeSector 

File name Sample .File 

The TypeSector program calls ErrorExit and 
returns to the Executive if an error is detected. 

The program consists of two modules, TypeSector 
and TypeArg. The modules are assembled and 
linked as follows: 
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Command Assemble 

Assemble 

Source files TypeSector . Asm 


Command 

Assemble 

Source 



Command Link 

Link 

Object modules TypeSector .Ob j TypeArg.Obj 
Run file TypeSector . Run 
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Public and external declarations. 


PUBLIC Main 

EXTRN RgParairuFAR, OpenFile :FAR, Read:FAR, CloseFile : FAR 
EXTRN WriteByte :FAR, WriteBsRecord : FAR, bsVid:BYTE 
EXTRN TypeArg : FAR 
EXTRN Exit: FAR, ErrorExit : FAR 
$ 

; Segment register default initialization. 

ASSUME CS :NOTHING, DS : NOTHING, ES : NOTHING, SS : NOTHING 
# 

; Segment declarations. 

; All segments used are mentioned in the order they are linked. 

TypeCode SEGMENT PUBLIC 'Code' 

TypeCode ENDS 

Const SEGMENT PUBLIC 'Const' 

Const ENDS 

Statics SEGMENT PUBLIC 'Const' 

Statics ENDS 

Data SEGMENT PUBLIC 'Data' 

Data ENDS 

Stack SEGMENT STACK 'Stack' 

Stack ENDS 

; Group the segments together for compatibility with Convergent 
; object modules. 

DGroup GROUP Const, Statics, Data, Stack 
/ 

; Stack declaration. 

; Declare lOOh bytes in this module. See the Linker /Librarian 
; Manual for combining stack segments in different modules. 

; raStackLim is placed so that the stack is the size of the sum 
; of all stack declarations. 

Stack SEGMENT 
DB lOOh DUP (?) 
raStackLim LABEL BYTE 
Stack ENDS 
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Data declarations . 

All of the variables used in this module are declared here. 


Data SEGMENT 
sDataRet DW ? 


sdRet DB 6 DUP (?) 


fh DW ? 


This is the variable 
that the CTOS Read 
calls and the byte 
stream WriteBsRecord 
uses to fill in the 
actual count of bytes 
read . 

This is the structure 
used to obtain 
parameters from the 
Executive. The sdRet 
structure is defined 
as a pointer (four 
bytes) followed by a 
count (two bytes). 

File handle for the 
source file. 


EVEN 

rgbBuf DB 512 DUP (?) 
DATA ENDS 


; Word-aligned input 
; buffer. 


Macro definition for checking errors. 


A procedure of ErcType returns the ere in register AX. If AX 
is nonzero, then simply call ErrorExit. 


$SAVE NOGEN 

%*DEFINE ( CheckErc ) LOCAL ok( 


AND 

AX, AX 

JE 

%ok 

PUSH 

AX 

CALL 

ErrorExit 

%ok: 

) 

%RESTORE 



; Main code segment follows. 
/ 

TypeCode SEGMENT 
ASSUME CS: TypeCode 
Main PROC FAR 
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Initialization . 

Set the segment registers (SS, DS) and stack. Since the 8086 
CPU chip disables interrupts for one instruction following a 
move to a segment register, there is no problem initializing 
the stack pointer (SP). 


Since the segment registers SS and DS are being initialized to 
DGroup, DGroup must be explicitly specified when referring to 
the offset of a variable. If this is not done, then the offset 
of a variable is from the start of the segment in which it is 
declared, not from the start of the group of segments. 


MOV 

AX, 

DGroup 

; Set SS. 

MOV 

SS, 

AX 


ASSUME SS 

: DGroup 



MOV 

SP, 

OFFSET DGroup: 

raStackLim 

MOV 

BP, 

SP 

; Set BP for 
; compatibility with 
; Convergent object 
; modules. 

PUSH 

SS 



POP 

DS 


; Set DS. 

ASSUME DS 

: DGroup 



/ 

; Type the parameter to the video 

display using TypeArg. 

/ 

; ere : = 

TypeArg (iParam, jParam) ; 


MOV 

> 

X 

1 

; iParam ( 1 ) . 

PUSH 

AX 



XOR 

AX, 

AX 

; jParam (0). 

PUSH 

AX 




CALL 

%CheckErc 


TypeArg 


Type a and a new line character, 

ere := WriteByte (pBSWA, b); 


PUSH 

DS 



; pBSWA 

(pBsVid) . 

MOV 

AX, 

OFFSET 

DGroup :bsVid 



PUSH 

AX 



; b ( : ) . 


MOV 

AX, 

1 : 1 



PUSH 

AX 





CALL 

WriteByte 




%CheckErc 

PUSH 

DS 



; pBSWA 

(pBsVid) . 

MOV 

AX, 

OFFSET 

DGroup :bsVid 



PUSH 

AX 




line) . 

MOV 

AX, 

OAh 


; b ( new 

PUSH 

AX 
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CALL 

WriteByte 




%CheckErc 





7 

; Get the file 

name from the 

Executive . 



; (parameter 1, 

subparameter 

0) 



/ 

; ere := RgParam (iParam, jParam, pSdRet) ; 



/ 

MOV 

AX, 1 

7 

iParam 

(1). 

PUSH 

AX 




XOR 

AX, AX 

7 

jParam 

(0) . 

PUSH 

AX 




PUSH 

DS 

7 

pSdRet . 



MOV AX, OFFSET DGroup: sdRet 

PUSH AX 

CALL RgParam 

%CheckErc 

Open the file for mode read. 


ere := OpenFile (pFh, pbFileSpec, cbFileSpec, pbPassword, 

cbPassword, mode); 


PUSH 

DS 


7 

pFh . 

MOV 

AX, 

OFFSET DGroup : fh 



PUSH 

AX 




PUSH 

word ptr sdRet + 2 

7 

pbFileSpec . 

PUSH 

word ptr sdRet 



PUSH 

word ptr sdRet + 4 

7 

cbFileSpec . 

XOR 

AX, 

AX 

7 

pbPassword (null). 

PUSH 

AX 




PUSH 

AX 




PUSH 

AX 


7 

cbPassword (0). 

MOV 

AX, 

' mr ' 

7 

mode . 

PUSH 

AX 




CALL 

OpenFile 



%CheckErc 





/ 

; Read in the 

first 

sector (512 bytes). 



7 

; ere := Read 

(fh. 

pBufferRet, sBufferMax 

# 

lfa, psDataRet) ; 

7 

PUSH 

fh 


7 

fh. 

PUSH 

DS 


7 

pBufferRet . 

MOV 

AX, 

OFFSET DGroup rrgbBuf 



PUSH 

AX 




MOV 

AX, 

512 

7 

sBufferMax . 

PUSH 

AX 




XOR 

AX, 

AX 

• 

/ 

lfa (0). 

PUSH 

AX 




PUSH 

AX 




PUSH 

DS 


• 

/ 

psDataRet. 

MOV 

AX, 

OFFSET DGroup rsDataRet 
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PUSH 

CALL 

%CheckErc 


AX 

Read 


Write the buffer to the video display. 

ere := WriteBsRecord (pBSWA, pb, cb, pcbRet) ; 


PUSH 

DS 


7 

pBSWA (pBsVid ) . 

MOV 

AX, 

OFFSET 

DGroup :bsVid 


PUSH 

AX 




PUSH 

DS 


7 

pb . 

MOV 

AX, 

OFFSET 

DGroup : rgbBuf 


PUSH 

AX 




MOV 

AX, 

512 

7 

cb . 

PUSH 

AX 




PUSH 

DS 


/ 

pcbRet . 

MOV 

AX, 

OFFSET 

DGroup : sDataRet 


PUSH 

AX 




CALL 

WriteBsRecord 


%CheckErc 






; Return to the Executive. 
7 

CALL Exit 

Main ENDP 


End of Main. 


TypeCode ENDS 


End of segment. 


END Main 


End of module 
(specify starting 
point as Main) . 
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The TypeArg procedure types a parameter passed 
from the Executive to the video display. It is 
called with two parameters, iParam and jParam, 
and is of the type ErcType. It can be called 
from Pascal as follows: 

ere := TypeArg (iParam, jParam); 

The procedure returns 0 if no errors were 
encountered; otherwise it returns the error in 
register AX. 

The procedure is reentrant and uses no static 
variables . 

This is not a main program but a procedure. It 
is assumed that the segment registers are 
properly set before calling this procedure, with 
DS and SS set to DGroup. 
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• Public and external declarations. 

/ 

PUBLIC TypeArg 

EXTRN RgParam:FAR, WriteBsRecord:FAR, bsVid:BYTE 

. The procedure uses 18 bytes of stack for itself, not counting 
; calls to other procedures, as follows: 

four bytes for parameters passed to it, 

• four bytes for the return address of the calling service, 

'. two bytes to store the BP of the calling service, and 

; eight bytes of local variables. 

Stack SEGMENT STACK 'Stack' 

DB 18 DUP (?) 

Stack ENDS 
DGroup GROUP Stack 

TypeArgCode SEGMENT 

ASSUME CS : TypeArgCode , DS: DGroup, ES: NOTHING, SS: DGroup 
TypeArg PROC FAR 

1 set the local variables and parameters as EQUs . 


sArgFrame EQU 4 


s Local Frame EQU 

8 


SUB 

SP, 

sLocalFrame 

PUSH 

BP 


MOV 

BP, 

SP 

iParam EQU WORD 

PTR 

[BP + 16] 


; Parameters to argument 
; are two words ( four 
; bytes ) . 

; Eight bytes of local 
; variables. 

• Save the calling 
; service's BP. 

; Use BP as a frame 
; pointer. 

; First parameter on 
; stack. 


jParam EQU WORD PTR [BP + 14] 

sdRet EQU BYTE PTR [BP + 2] 
pbArg EQU DWORD PTR [BP + 2] 
cbArg EQU WORD PTR [BP + 6] 


; Second parameter on 
; stack. 

; sdRet is a 6-byte 
; structure consisting 
; of a pointer (pbArg; 

; four bytes) and a 
; count (cbArg; two 
; bytes) located on the 
; stack at SS:[BP +2] 

; to SS : [BP + 7]. 
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sDataRet EQU WORD PTR [BP + 8] 


sDataRet is the count 
of bytes actually 
written to the video 
display, and is 
ignored in this 
procedure . 

ere := RgParam (iParam, jParam, pSdRet) ; 


PUSH 

iParam 

; iParam. 

PUSH 

jParam 

; jParam. 

LEA 

AX, sdRet 

; pSdRet. 

PUSH 

SS 


PUSH 

AX 


CALL 

RgParam 


AND 

AX, AX 

? Check for errors. 

JNZ 

Finish 


/ 

? ere : = 
7 

WriteBsRecord (pBSWA, pb. 

cb, pcbRet); 

PUSH 

DS 

; pBSWA (pBsVid). 

MOV 

AX, OFFSET DGroup : 

bsVid 

PUSH 

AX 


LES 

AX, pbArg 

? pb. 

PUSH 

ES 


PUSH 

AX 


PUSH 

cbArg 

; cb . 

LEA 

AX, sDataRet 

; pcbRet. 

PUSH 

SS 


PUSH 

AX 


CALL 

WriteBsRecord 


1 

; All done, so return ere in AX. 


/ 

Finish: 

POP 

BP 

; Restore the BP of the 

ADD 

SP, sLocalFrame 

; calling service. 
; Remove the local 

RET 

sArg Frame 

; variables from the 
; stack. 

; Return with arguments 


(four bytes) removed 
from the stack. 


TypeArg ENDP 
TypeArgCode ENDS 
END 
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Example 2 


The Timer program uses the Programmable Interval 
Timer (8253 chip) to generate interrupts and then 
waits for five interrupts before returning to the 
Executive . 

This example only executes correctly on a 
standalone workstation because the PIT is used by 
the CTOS OS at cluster and master workstations. 
This example demonstrates interrupt handling and 
is not intended for actual use. The SetTimerlnt 
operation is used to control the PIT. (See the 
"Timer Management" section.) 

The Timer program has two parts: the main 
program and the interrupt handler. The main 
program sets the interrupt handler as raw, using 
the CTOS SetlntHandler operation. When this is 
done, it loops until a flag is set by the 
interrupt handler, and then displays an * on the 
video display and resets the flag. When this is 
done five times, it returns to the Executive. 

The interrupt handler, RawTimerHandler , is 
entered when the 8253 timer counter reaches 0 and 
generates an interrupt. Because the interrupt is 
raw, the handler must preserve the register state 
and send an EOI ( end-of-interrupt ) to the 8259A 
when the interrupt service is completed. The 
handler does this and also sets the register DS 
to DGroup before calling the actual service 
procedure, TimerHandler , which sets a flag and 
then restarts the timer. 


Conversion to Mediated Interrupt Handler 

While Timer sets and uses a raw interrupt 
handler, it can easily be converted to use a 
mediated interrupt handler. Necessary changes in 
the module are as follows: 

1. Change the Equate for fRawInterrupt to FALSE: 

f Rawlnterrupt EQTJ FALSE 

2. Change the procedure offset pushed on the 
stack before the call to SetlntHandler to be 
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TimerHand ler (instead of RawTimerHandler , 
which calls TimerHandler ) : 

MOV AX, OFFSET TimerHandler 
PUSH AX 

3. Delete the handler RawTimerHandler and remove 
its PUBLIC declaration, since it will no 
longer be used. 


Program Assembly and Linking 

The program is assembled and linked as follows: 

Command Assemble 

Assemble 

Source files Timer .Asm 

Command Link 

Link ‘ 

Object modules Timer ,0b j 
Run file Timer . Run 


References 


The information required to create the Timer 
program was found in the documentation below: 

CTOS Interrupt Interface 

"Interrupt Handler" section of this Manual. 

8253 Programmable Interval Timer 

"Interrupt Handler" section of this Manual, and 
"Functions and Interfaces" section of the 

Workstation Hardware Manual ♦ 

8259A Interrupt Controller 

"Interrupt Handler" section of this Manual, and 
"Functions and Interfaces" section of the 

Workstation Hardware Manual . 

WriteByte 

"Sequential Access Method" section of this 

Manual . 

bsVid 

"Sequential Access Method" section of this 

Manual . 
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; Public and external declarations . Symbols are made public so 
; that they are included in the symbol file produced by the 

; Linker. 

• 

PUBLIC, Main, PutChar, RawTimerHandler , TimerHandler 
EXTRN WriteByte : FAR, bsVidrBYTE 
EXTRN SetlntHandler : FAR 
EXTRN Exit: FAR, ErrorExit : FAR 

t 

; Segment register default ASSUMES. 

ASSUME CS : NOTHING, DS : NOTHING, ES :NOTHING, SSrNOTHING 

I 

; Segment declarations. 

; All segments used are mentioned in the order they are linked. 

TimerCode SEGMENT PUBLIC 'Code' 

TimerCode ENDS 

Const SEGMENT PUBLIC 'Const' 

Const ENDS 

Statics SEGMENT PUBLIC 'Const' 

Statics ENDS 

Data SEGMENT PUBLIC 'Data' 

Data ENDS 

Stack SEGMENT STACK 'Stack' 

Stack ENDS 

; Group the segments together for compatibility with object 
; modules. 

i 

DGroup GROUP Const, Statics, Data, Stack 

l 

; Stack declaration. 

; Declare lOOh bytes in this module. See the Linker/Librarian 
; Manual for combining stack segments in different modules. 

; raStackLim is placed so that the stack is the size of the sum 
; of all stack declarations. The stack must be large enough for 
; requests to be built by the CTOS procedural interface, and for 
; the OS to save the process state when the process is swapped 
; out for any reason. 

Stack SEGMENT 
DB lOOh DUP (?) 
raStackLim LABEL BYTE 
Stack ENDS 
/ 

; Data declarations. 

; All of the variables and constants used in this module are 
; declared here. 


F-16 CTOS" Operating System Manual 



Data SEGMENT 
flnterrupt DW ? 

clnterrupts DW ? 

cbRet DW ? 

DATA ends 
7 

; Equates used in module. 
/ 

; Boolean values. 


TRUE 

EQU OFFFFh 


FALSE 

EQU 0 


f Rawlnterrupt 

EQU TRUE 


7 

; 8253 Timer 

• 

Equates . 


/ 

ilnterrupt 

EQU 11 


reg8253CntO 

EQU 28h 


reg8253Mode 

EQU 2 Eh 


cmdMode 

EQU 3 Oh 

Select Counter 0, Load 
lsb, then Msb, Mode 0, 
Binary Counter 16 
bits . 

bDataLsb 

EQU OFFh 


bDataMsb 

EQU OFFh 


/ 

; 8259A Interrupt Equates. 


reg8259aISR 

EQU 2 Oh 


reg8259aIMR 

EQU 22h 


cmdEOI 

EQU 2 Oh 

Nonspecific EOI. 

maskTimerOf f 

EQU 8h 

This is OR'ed with the 
value read from IMR 
( Interrupt Mask 
Register) . 

maskTimerOn 

EQU 0F7h 

This is AND'ed with 
the value read from 
IMR. 


Macro definition for checking errors. 

A procedure of ErcType returns the ere in register AX. If AX 
is nonzero, then simply call ErrorExit. 


CTOS from Assembly Language F— 17 



$SAVE NOGEN 

%*DEFINE ( CheckErc ) LOCAL ok( 


AND 

AX, AX 

JE 

%ok 

PUSH 

AX 

CALL 

%ok: 

) 

$RESTORE 

ErrorExit 


; Main code segment follows. 

7 

TimerCode SEGMENT 
saDGroup DW DGroup 

ASSUME CS : TimerCode , DS : NOTHING , SS:NOTHING, ES : NOTHING 
Main PROC FAR 
7 

; Set segment, stack, and frame registers. 

7 

MOV SS, saDGroup 

ASSUME SS: DGroup 

MOV SP, OFFSET DGroup : raStackLim 

MOV BP, SP 

PUSH SS 

POP DS 

ASSUME DS: DGroup 
/ 

• Set the interrupt handler. 

; ere := SetlntHandler ( ilnt , plntHandler, saData, fDevicelnt, 

fRaw) ; 


MOV 

AX, ilnterrupt 

7 

ilnt. 

PUSH 

AX 



PUSH 

CS 

7 

plntHandler . 

MOV 

AX, OFFSET RawTimerHandler 


PUSH 

AX 



PUSH 

DS 

/ 

saData (not used 



7 

f Rawlnterrupt is 



7 

TRUE) . 

MOV 

AX, TRUE 

7 

fDevicelnt . 

PUSH 

AX 



MOV 

AX, f Rawlnterrupt 



PUSH 

AX 

7 

fRaw. 

CALL 

SetlntHandler 



%CheckErc 





Start the 8253 timer. 

CL I 

MOV AL, cmdMode ; Initialize counter 0. 

OUT reg8253Mode, AL 

MOV AL, bDataLsb 
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OUT 

reg8253CntO, AL 


MOV 

AL, bDataMsb 


OUT 

reg8253CntO, AL 


IN 

AL, reg8259aIMR 

y Turn 8259A mask bit 
y on. 

AND 

AL, maskTimerON 


OUT 

reg8259aIMR, AL 


MOV 

AX, 5 

y Initialize counter. 

MOV 

clnterrupts, AX 


MOV 

AX, FLASE 

; Initialize flag. 

MOV 

f Interrupt, AX 

ST I 




Loop until counter is decremented to 0. 


MainLoop: 


y Access to 

the flag must be with interrupts disabled. 

CLI 


y Get the flag value. 

MOV 

BX, flnterrupt 

MOV 

AX, FALSE 

y Reset flag. 

MOV 

flnterrupt, AX 

ST I 

CMP 

BX, TRUE 

y Check for interrupt 

JNE 

MainLoop 


/ 

y Interrupt 

occurred, so display a 

character and decrement 

y counter. 

/ 

MOV 

AL, 


PUSH 

AX 


CALL 

PutChar 


DEC 

clnterrupts 


JNZ 

MainLoop 


1 

y Received five interrupts, so quit 

• 

• 

CALL 

Exit 

y Return to Executive 

Main ENDP 


y End of Main. 

/ 

y PutChar — 

Write one character to 

the video display. 

t 

y Syntax : 

; MOV 

AL, char 


y PUSH 

AX 


y CALL 

* 

PutChar 


PutChar PROC 

NEAR 


PUSH 

BP 


MOV 

BP, SP 
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SArgFrame EQU 2 
s Ret Frame EQU 2 

bChar EQU BYTE PTR SS:[BP + SArgFrame + sRetFrame] 
; ere := WriteByte (pBSWA, b) ; 


MOV 

AX, SEG bsVid 

; pBSWA. 

PUSH 

AX 


MOV 

AX, OFFSET bsVid 


PUSH 

AX 


MOV 

AL, bChar 

; b- 

PUSH 

AX 


CALL 

WriteByte 


%CheckErc 



POP 

BP 


RET 

sRetFrame 



PutChar ENDP 
/ 

; RawTimerHandler . 

; This handler preserves the state of the registers of the 
; interrupted process, sets the data segments to DGroup, and 
; then calls TimerHandler . When TimerHandler returns, it 
; restores the register state and sends the required EOI to the 
; 8259A interrupt controller. 

; The routine assumes that TimerHandler uses no registers besides 
; AX and DX. 

ASSUME CS : TimerCode , DS -.NOTHING, SS: NOTHING 
RawTimerHandler PROC FAR 

PUSH DS ; Save DS, AX. 

PUSH AX 

MOV DS, saDGroup ; Put in local DS. 

ASSUME DS : DGroup 

CALL FAR PTR TimerHandler 

MOV AL, cmdEOI ; Specify EOI to 8259A. 

OUT reg8259aISR, AL 

POP AX ; Restore old DS, AX. 

POP DS 

ASSUME DS: NOTHING 

I PET ; Return from interrupt. 

RawTimerHandler ENDP 

r 

; TimerHandler. 

; This procedure sets the flag for main program to look at, 

; restarts the timer, and then returns. 

; The procedure requires DS to be set to DGroup, and it uses AX. 
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ASSUME CS : TimerCode , DS:DGroup, SS: NOTHING 


TimerHandler 

PROC FAR 


MOV 

AX, TRUE 


MOV 

flnterrupt, . 

AX 

MOV 

AL , cmdMode 


OUT 

reg8253Mode, 

AL 

MOV 

AL, bDataLsb 


OUT 

reg8253CntO, 

AL 

MOV 

AL, bDataMsb 


OUT 

reg8352CntO, 

AL 

RET 




TimerHandler ENDP 
TimerCode ENDS 
END Main 


Set interrupt flag. 
Reinitialize counter. 


End of segment. 
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APPENDIX G: CTOS OPERATIONS 


Operation Name Page 


AddQueueEntry 15-16 

AllocAllMemorySL 6-11 

AllocExch 5-4 

Al 1 ocM emo ry LL 6-13 

AllocMemorySL 6-14 

Beep 26-15 

Chain 7-7 

ChangeFileLength 14-23 

ChangePriority 3-8 

Check 4-27 

CheckpointBs 17-21 

CheckpointRsFile 18-4 

CheckpointSysIn 26-16 

CheckReadAsync (File Management) 14-24 

CheckReadAsync (Disk Management) 21-6 

CheckWriteAsync (File Management) 14-25 

CheckWriteAsync (Disk Management) 21-7 

ClearPath 14-26 

CloseAllFiles 14-27 

CloseAllFilesLL 14-28 

CloseByteStream . 17-22 

CloseDaFile 19-6 

CloseFile (File Management) 14-29 

CloseFile (Disk Management) 21-8 

CloseRsFile 18-5 

CloseRTClock 28-12 

Compact Da teTime 28-13 

Conf igureSpooler 22-5 

ConvertToSys 13-7 

CParams 9-10 

Crash 30-3 

CreateDir 14-30 

CreateFile 14-32 

CreatePartition 10-14 

CreateProcess 3-9 

CSubParams 9-11 

DeallocExch 5-5 

Deal locM emo ryLL 6-15 

DeallocMemorySL 6-16 

Delay 28-14 

DeleteDaRecord 19-7 

DeleteDir 14-34 

DeleteFile 14-35 

DisableActionFinish 26-17 

DisableCluster 11-6 

Dismount Volume 21-9 

ErrorExit 7-10 

EstablishQueueServer . 15-18 

Exit 7-12 
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Page 


Operation Name 


ExpandDateTime 28-15 

FatalError 30-4 

Format 21-11 

GetBsLfa 17-23 

GetClusterStatus 11-8 

GetDateTime 28-16 

GetFhLongevity 14-36 

GetFileStatus 14-37 

GetPartitionEx change 10-16 

GetPartitionHandle 10-17 

GetPartitionStatus 10-18 

GetpASCB 9-12 

GetRsLfa. . 18 “ 6 

GetStamFileHeader 16-11 

GetUCB 14-39 

3-12 

GetVHB 21-13 

InitCharMap 24-5 

InitOverlays 8-7 

InitVidFrame 24-7 

LoadCursorRam 24-11 

LoadFontRam 24-12 

LoadPrimaryTask 10-20 

LoadStyleRam 24-14 

LoadTask 7-13 

Lockln 27-3 

Lockout 27-4 

MarkKeyedQueueEntry 15-20 

MarkNextQueueEntry 15-23 

MediatelntHandler 29-15 

MountVolume 21-15 

OpenByteStream 17-24 

OpenDaFile 19-8 

OpenFile (File Management) 14-40 

OpenFile (Disk Management) 21-17 

OpenFileLL 14-42 

OpenRsFile 18-7 

OpenRTClock 28-17 

PosFrameCursor 25-3 

PSend 4-28 

PutBackByte 17-26 

PutFrameAttrs 25-4 

PutFrameChars 25-6 

QueryDaLastRecord 19-10 

QueryDaRecordStatus 19-11 

QueryDCB 21-19 

QueryDefaultRespExch 5-6 

QueryExitRunFile 7-15 

QueryFrameChar 25-7 

QueryKbdLeds 26-18 

QueryKbdState 26-19 
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Operation Name 


Page 


QueryMeraAvail 

QueryProcessNuraber . ......... 

QueryVidBs .................. 

QueryVidHdw. ................ 

QueryWSNum. ................. 

Read (File Management) ...... 

Read (Disk Management) ...... 

ReadActionCode .............. 

ReadAsync (File Management). 
ReadAsync (Disk Management) . 

ReadBsRecord 

ReadByte 

ReadBytes 

ReadDaFragment . . 

ReadDaRecord . . 

ReadDirSector 

ReadKbd . . , 


ReadKbdDirect 

ReadKeyedQeueueEntry 

ReadNextQueueEntry . ....... 

ReadRsRecord 

ReleaseBy test ream 

ReleaseRsFile 

RemoveKeyedQueueEntry 

RemoveMarkedQueueEntry . . . . 

RemovePartition. 

RenameFile 

Request 

ResetCommISR. 

ResetFrame 

ResetMemoryLL 

ResetTimerlnt 

ResetVideo 

Respond 

RewriteMarkedQueueEntry. . . 

RgParam 

RgParamlnit 

RgParamSetEltNext 

RgParamSetListStart . ...... 

RgParamSetSimple 

ScanToGoodRsRecord 

ScrollFrame 

Send 

ServeRq 

SetBsLfa 

SetCommISR 

SetDaBuf ferMode. 

SetDateTime 

SetDevParams . . . . . . 

SetExitRunFile 

SetFhLongevity . . 




6-17 

3-13 

17-27 

24- 15 
14-44 
14-45 
21-21 
26-21 
14-47 
21-23 
17-28 
17-29 
17-30 
19-12 
19-13 

14- 48 
26-22 
26-23 

15- 25 
15-27 

18-9 

17- 31 

18- 10 
15-29 
15-31 
10-22 

14- 50 
4-29 

29-16 

25- 8 
6-18 

28-18 

24-17 

4-30 

15- 32 
9-13 
9-14 
9-15 
9-16 
9-17 

18-11 

25-9 

4-31 

13-8 

17-32 

29-17 

19-14 

28-19 

21-25 

7-17 

14-52 
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Operation Name Page 


SetFileStatus 14-53 

SetlmageMode 17-33 

SetlntHandler 29-19 

SetKbdLed 26-25 

SetKbdUnencodedMode 26-26 

SetLpISR 29-21 

SetPartitionExcbange 10-23 

SetPartitionLock 10-24 

SetPath 14-55 

SetPrefix 14-56 

SetScreenVidAttr 24-19 

SetSysInMode 26-27 

SetTimerlnt 28-20 

SpoolerPassword 22-7 

TerminatePartitionTasks 10-25 

TerminateQueueServer 15-34 

TruncateDaFile 19-15 

UnmarkQueueEntry 15-35 

VacatePartition 10-26 

Wait 4-32 

Write (File Management) 14-57 

Write (Disk Management) 21-27 

WriteAsync (File Management) 14-59 

WriteAsync (Disk Management) 21-29 

WriteBsRecord 17-34 

WriteByte 17-35 

WriteDaFragment 19-16 

WriteDaRecord 19-17 

WriteLog 30-5 

WriteRsRecord 18-13 
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$ Directories. The $ Directories are special 
directories required for the Convergent software 
to operate correctly. When a request with the 
directory name of <$> is given as part of a file 
specification to the OS, the directory name is 
expanded to the form <$ nnn> , where nnn is the 
user number of the application system. 

Action Code. An action code is a key (CANCEL, 
HELP, 0-9, or fl-flO) depressed in conjunction 
with the ACTION key. Also see ACTION Key. 

ACTION Key. The ACTION key is a special kind of 
SHIFT key. It is processed specially, even in 
unencoded mode. The interpretation of all other 
keys is modified while ACTION is depressed. The 
key combination ACTION-FINISH terminates the 
execution of the application system in the 
primary application partition and invokes the 
Executive. The key combinations ACTION-A and 
ACTION-B invoke the Debugger if the Debugger is 
included in the system at system build. Some of 
the key combinations that include the ACTION key 
are available for interpretation by the 
application system in the primary application 
partition. This allows the application system to 
test for special operator intervention without 
preventing type ahead. Key combinations that 
include the ACTION key are processed immediately 
when they are typed. This processing is 
independent of characters or keyboard codes 
stored in the type-ahead buffer. Also see Action 
Code . 

Advanced Video Capability. Advanced video 
capabilities are provided by workstations in the 
IWS family with an optional board added to the 
standard video board. Several versions of this 
optional board provide various capabilities (for 
example, bold characters, double-height 
characters, double-width characters, or a 512 
character set) that augment the standard video 
capabilities of the IWS family of workstations. 
Also see Basic Video Capability, Standard Video 
Capability, and Video Capability. 

Agent Service Process. See CWS Agent Service 
Process or Master Workstation Agent Service 
Process . 
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Allocation Bit Map. The Allocation Bit Map 
controls the assignment of disk sectors. It has 
1 bit for every sector on the disk and the bit is 
set if the sector is available. The Allocation 
Bit Map is disk-resident. 

Application Partition. An application partition 
is a partition of user memory in which an 
application system can be executed. A 
workstation can have any number of application 
partitions, with an application system executing 
concurrently in each. Also see Primary 
Application Partition, Secondary Application 
Partition, and System Partition. 

Application Partition Management. The 
application partition management facility permits 
concurrent execution of multiple application 
systems, each in its own partition. It provides 
operations for creating, managing, and removing 
secondary application partitions. Also see 
Application Partition, Primary Application 
Partition, and Secondary Application 
Partition. 

Application Process. An application process 
executes code in the application system. It is 
not a system service process. Also see System 
Service Process. 

Application System. An application system is the 
collection of all tasks currently in an 
application partition. The tasks in an 
application system access a common set of files 
and implement a single application. The tasks 
execute asynchronously. Also see Task and 
Application Partition. 

Application System Control Block. The 
Application System Control Block (ASCB) 
communicates parameters, the termination code, 
and other information between an exiting 
application system and a succeeding application 
system in the same partition. Also see the 
Variable-Length Parameter Block. 

Application Workstation. See AWS Workstation. 

ASCB. See Application System Control Block. 

Asynchronous Terminal Emulator. The Asynchronous 
Terminal Emulator (ATE) utility allows a 
workstation to emulate an asynchronous char act er- 
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oriented ASCII terminal (glass TTY). See the 
Asynchronous Terminal Emulator Manual for more 
information . 

ATE. See Asynchronous Terminal Emulator. 

AWS Workstation. An AWS workstation is a 
Convergent workstation that has basic video 
capabilities and no Multibus slots. Also see 
Basic Video Capability and IWS Workstation 
Workstation. 

Bad Sector File. The Bad Sector File contains an 
entry for each unusable sector of a disk. The 
Bad Sector File is 1 sector in size. 

Banner Page. A banner page is optionally 
printed by the printer spooler before the 
printing of each file. The banner page is 
visually distinctive and also identifies the file 
being printed. The banner page can contain the 
text of a notice file. Also see Notice File and 
Printer Spooler. 

Basic Video Capability. Basic video capabilities 
are provided by the AWS workstation. These 
capabilities are characterized by an 80-character 
by 28-line screen, one cursor on the screen, a 
256 character set that cannot be modified by 
software, and a screen split horizontally into 
multiple frames. Also see Advanced Vicleo 
Capability, Standard Video Capability, and Video 
Capability. 

Batch Control Block. The Batch Control Block, 
which is used by the batch manager, contains the 
job name and class, file handle and logical file 
address of the batch job control file. Assigned 
Device Block, and Sysln and SysOut Byte Stream 
Work Area and buffers. Also see Batch Job 
Stream, Assigned Device Block, and the Batch 
Manual . 

Batch Job Control File. See Batch Job Stream, 
and the Batch Manual . 

Batch Job Stream. A batch job stream is a file 
containing batch control statements that is used 
by the batch manager to direct the execution of 
noninteractive application systems. Also see the 
Batch Manual . 
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Batch Manager. The batch manager is a system 
service that uses the batch control statements in 
a batch job stream to direct the loading and 
execution of noninteractive application 
systems. Also see the Batch Manual . 

Batch Partition. A batch partition is an 
application partition that is under the control 
of the batch manager. Also see Batch Manager, 
Batch Job Stream, and the Batch Manual . 

Binary Mode. Binary mode is one of three 
printing mode options in the printer, printer 
spooler, and communications byte streams. Binary 
mode does not print the banner page before each 
file, send extra code not in the file to the 
printer, nor recognize the escape sequence. Also 
see Image Mode and Normal Mode. 

Blocked. A record file with several records per 
physical sector is blocked. Also see Record 
Sequential Access Method and Spanned. 

Bootstrap. To bootstrap (or boot) the system is 
to start it by reloading the Operating System 
from disk. On other systems, this is often known 
as Initial Program Load (IPL). 

BSWA. See Byte Stream Work Area. 

Buffer Management Modes. The Direct Access 
Method provides two modes of buffer management, 
write-through and write-behind . Also see Write- 
Behind Mode and Write-Through Mode. 

Byte Stream. A byte stream, a concept of the 
Sequential Access Method, is a readable (input) 
or writable (output) sequence of 8-bit bytes. An 
input byte stream can be read until either the 
reader chooses to stop reading or it receives 
status code 1 ("End of File"). An output byte 
stream can be written until the writer chooses to 
stop writing. Also see Byte Stream Work Area, 
Communications Byte Stream, File Byte Stream, 
Keyboard Byte Stream, Printer Byte Stream, 
Sequential Access Method, Spooler Byte Stream, 
Video Byte Stream, and X.25 Byte Stream. 

Byte Stream Work Area. The Byte Stream Work Area 
is a 130-byte memory work area for the exclusive 
use of Sequential Access Method procedures. Any 
number of byte streams can be open concurrently, 
using separate Byte Stream Work Areas. Also see 
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Byte Stream, Communications Byte Stream, File 
Byte Stream, Keyboard Byte Stream, Printer Byte 
Stream, Sequential Access Method, Spooler Byte 
Stream, Video Byte Stream, and X.25 Byte Stream. 

cb. A cb is the count of bytes in a string of 
bytes . 

Character Attribute. A character attribute 
controls the presentation of a single 
character. The standard character attributes are 
reverse video, blinking, half-bright, and 
underlining. Also see Line Attribute, Screen 
Attribute, and Video Attributes. 

Character Code. In character mode, the 8-bit 
byte returned by certain keyboard management 
operations is called a character code (in 
contrast to the keyboard code returned when the 
keyboard is in unencoded mode) . The character 
code signifies the depression of a key other than 
SHIFT, CODE, LOCK, or ACTION. Depression of 
SHIFT, CODE, and LOCK does not generate a 
character code, but influences the character 
codes generated for other keys depressed 
concurrently. ACTION has a special, system-wide 
meaning. Also see Character Mode. 

Character Map. The character map is the area of 
memory that holds the coded representation of the 
characters displayed on the video display. Also 
see Video Refresh. 

Character Mode. In character mode (the default 
mode) , the client process receives an 8-bit 
character when a key other than SHIFT, CODE, 
LOCK, or ACTION is pressed. Also see Character 
Code and Unencoded Mode . 

Character Set. See Standard Character Set. 

CISR. See Communications Interrupt Service 
Routine . 

Client Process. A client process is a process 
that makes a request of a system service. Any 
process, even a CTOS process, can be a client 
process since any process can request system 
services. Also see Queue Manager and System 
Service Process. 
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Cluster Configuration. A cluster configuration 
is a local resource-sharing network consisting of 
a master workstation and up to 16 cluster 
workstations. A cluster is connected by one to 
four high-speed multidrop half-duplex data links 
using a variant of the ADCCP/HDLC bit-oriented 
synchronous protocol. The CTOS OS executes in 
each cluster workstation and in the master 
workstation. Also see Cluster Workstation, 
CommlOP, Master Workstation, and Minicluster. 

Cluster Workstation. A cluster workstation is a 
workstation in a cluster configuration and is 
connected to a master workstation. Also see 
Cluster and Master Workstation. 

Code Segment. A code segment is a variable- 
length (up to 64k bytes) logical entity 
consisting of reentrant code and containing one 
or more complete procedures. Also see Data 
Segment, Segment, and Virtual Code Segment 
Swapping . 

CommlOP. The CommlOP is an intelligent 
communications processor based on the Intel 8085 
microprocessor. The CommlOP serves up to four 
cluster workstations on each of its two high- 
speed serial input/output channels. The CommlOP 
is installed in the Multibus slot of workstations 
in the IWS family. CommlOP software consists 
of: the 8085 bootstrap-ROM program, the main 
CommlOP program, and the CommlOP handler . 

Common Memory Pool. The common memory pool is a 
single contiguous area of memory in each 
application partition from which long-lived and 
short-lived memory segments are allocated. 

Communications Byte Stream. A communications 
byte stream is a byte stream that uses a 
communications channel. Also see Byte Stream, 
Byte Stream Work Area, File Byte Stream, Keyboard 
Byte Stream, Printer Byte Stream, Sequential 
Access Method, Spooler Byte Stream, Video Byte 
Stream, and X.25 Byte Stream. 

Communications Interrupt Service Routine. A 
Communications Interrupt Service Routine (CISR) 
is similar to a mediated interrupt handler except 
that a CISR serves only one of the two 
communications channels of the SIO communications 
controller . 
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Compact System. A compact system is a version of 
the CTOS Operating System that provides all 
Operating System functions except for the 
concurrent execution of multiple application 
systems. A compact system has a primary 
application partition and can execute application 
systems one at a time. An OS is specified to be 
compact during system build. 

Configuration File. A configuration file 
specifies the characteristics of either the 
parallel printer, the serial printer, or other 
device attached to a communications channel. 
Examples of characteristics are number of 
characters per line, baud rate, and line control 
mode (XON/XOFF, CTS). A configuration file is 
created by the Create Configuration File utility 
( see the System Utilities Manual ) and is used by 
printer, printer spooler, and communications byte 
streams . 

Context Switch. A context switch is the saving 
of register contents when a process is 
interrupted. When a process is preempted by a 
process with a higher priority, the OS saves the 
hardware context of the preempted process in that 
process’s Process Control Block. When the 
preempted process is rescheduled for execution, 
the OS restores the contents of the registers. 
The context switch permits the process to resume 
as though it were never interrupted. Also see 
Process, Process Context, and Process Control 
Block. 

Contingency. A contingency can refer to a 
variety of hardware and software conditions that 
have undesirable effects. These conditions can 
be hardware faults such as a memory parity error, 
inconsistencies detected by the OS such as a bad 
checksum of a Volume Home Block, or conditions 
detected by the application system. The OS 
always terminates execution when it detects an 
inconsistency . 

CPU. The CPU (central processing unit) is the 
8086 or 8088 microprocessor. 

Crash Dump Area. The Crash Dump Area (the file 
[Sys] <Sys>CrashDump.Sys) contains a binary memory 
dump in the event of a system failure. 

CT. Convergent Technologies. 
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CT-NET Network. The CT-NET Network provides 
access to the system services of interconnected 
Convergent cluster configurations and standalone 
workstations. It uses high-speed local data 
links, leased telephone lines, and packet- 
switched networks. 

CTOS. Convergent Technologies Operating System. 

Cursor RAM. The cursor RAM, part of the advanced 
video capability, allows software to specify a 10 
by 15 bit array as a pattern of pixels in place 
of the standard cursor (a blinking underline) . 
The cursor bit array is superimposed on the 
character and blinks. 

CWS. See Cluster Workstation. 

CWS Agent Service Process. The CWS Agent Service 
Process converts interprocess requests to 
interstation messages for transmission to the 
master workstation. The CWS Agent Service 
Process is included at system build in a System 
Image that is to be used on a CWS. Also see 
Master Workstation Agent Service Process. 

DAM. See Direct Access Method. 

Data Segment. A data segment contains data. It 
can also contain code, although this is not 
recommended. If a data segment is shared among 
processes, concurrency control is the 
responsibility of those processes. A data 
segment that is automatically loaded into memory 
when its containing task image is loaded is 
called a static data segment to differentiate it 
from a dynamic data segment that is allocated by 
a request from the executing process to the 
memory management facility. Also see Code 
Segment, Segment, and Task Image. 

Date/Time Format. The Convergent date/time 
format provides a compact representation of the 
date and the time of day that precludes invalid 
dates and allows simple subtraction to compute 
the interval between two dates. The date/time 
format is represented in 32 bits to an accuracy 
of one second. 

DAWA. See Direct Access Work Area. 

DCB. See Device Control Block. 
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Default Response Exchange. Each process is given 
a unique default response exchange when it is 
created. This special exchange is automatically 
used as the response exchange whenever a client 
process uses the procedural interface to a system 
service. For this reason, the direct use of the 
default response exchange is not recommended. 
The use of the default response exchange is 
limited to requests of a synchronous nature. 
That is, the client process, after specifying the 
exchange in a Request, must wait for a response 
before specifying it again (indirectly or 
directly) in another Request. Also see Exchange 
and Response Exchange. 

Device. A device is a physical hardware 
entity. Printers, tape, floppy disks, and 
Winchester disks are examples of devices. 

Device Control Block. There is a Device Control 
Block ( DCB ) for each physical device. The DCB 
contains information, generated at system build, 
about the device. For a disk, the information 
includes how many tracks are on a disk, the 
number of sectors per track, etc. The DCB points 
to a chain of I/O Blocks. The DCB is memory- 
resident. 

Device Password. A device password protects a 
device. 

Device Specification. A device specification 
consists of a devname (device name) . 

Devname . (Device name) A devname is the only 
element of a device specification. 

Direct Access Method. The Direct Access Method 
provides random access to disk file records 
identified by record number. The record size is 
specified when the DAM file is created. DAM 
supports COBOL Relative 1-0, but can also be 
called directly from any of the Convergent 
languages. Also see Direct Access Work Area. 

Direct Access Work Area. A Direct Access Work 
Area is a 64-byte memory work area for the 
exclusive use of the Direct Access Method 
procedures. Any number of DAM files can be open 
simultaneously using separate DAWAs . Also see 
Direct Access Method. 
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Direct Printing. Direct printing transfers text 
directly from application system partition memory 
to the specified parallel or serial printer 
interface of the workstation on which the 
application system is executing. Direct printing 
is always accessed through the Sequential Access 
Method (printer byte streams) . Also see Printer 
Byte Stream, Spooled Printing, and Spooler Byte 
Stream. 

Directory. A directory is a collection of 
related files on one volume. A directory is 
protected by a directory password. 

Directory Password. A directory password 
protects a directory on a volume. 

Directory Specification. A directory 
specification consists of a node (node name), 
volname (volume name), and a dirname (directory 
name) . 

Dirname. (Directory name) A dirname is the 
third element of a directory specification or a 
full file specification. 

Disk Extent. A disk extent is one or more 
contiguous disk sectors that compose all or part 
of a file. 

DMA. See Direct Memory Access. 

Dynamic Data Segment. See Data Segment. 

Dynamically Installed System Service. A 
dynamically installed system service is a system 
service process that was loaded as an application 
system and converted itself into a system service 
using the ConvertToSys operation. (See the 
"System Services Management" section.) Once 
installed, a dynamically installed system service 
has the same capabilities as a system service 
process that was linked to the System Image. A 
dynamically installed system service must use 
CTOS operations (rather than system build 
parameters) to identify the request codes that it 
serves, specify its execution priority, establish 
its interrupt handlers, etc. 

Ere. An Ere is a status (error) code. 

Escape Sequence. An escape sequence is a special 
sequence of characters that invokes special 
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functions. Also see Printer Spooler Escape 
Sequence, Submit File Escape Sequence, and Video 
Byte Stream. 

Event. In the context of timer management, an 
event occurs when an interval elapses. Also see 
System Event . 

Event-driven Priority Scheduling. Event-driven 
priority scheduling means that processes are 
scheduled for execution based on their priorities 
and system events, not on a time limit imposed by 
the CTOS scheduler. Also see Process and System 
Event . 

Exchange. An exchange is the path over which 
messages are communicated from process to process 
(or from interrupt handler to process). An 
exchange consists of two first-in, first-out 
queues, one of processes waiting for messages, 
the other of messages for which no process has 
yet waited. An exchange is referred to by a 
unique 16-bit integer. Also see Default Response 
Exchange and Response Exchange. 

Executive. An Executive is an interactive 
application program that can be executed in the 
primary application partition. It accepts 
commands from the workstation operator and 
requests the’ OS to load tasks to execute those 
commands. This function can be performed by the 
Convergent Executive or by a user-written 
Executive. The Executive is loaded from the file 
[Sys]<Sys>Exec.Run if specified as the 
SignOnExitFile . (See the Release Notice for the 
current CTOS version.) The file 
[Sys] <Sys> Exec . Run usually contains the 
Convergent Executive; however, it can contain a 
user-written Executive. 

Exit Run File. An exit run file is a user- 
specified file that is loaded and activated when 
an application system exits. Each application 
partition has its own exit run file. 

Extended Partition Descriptor. An Extended 
Partition Descriptor is located in each 
application partition and contains specifications 
for the current application file and exit run 
f ile . 

Extended User Control Block. An Extended User 
Control Block is located in each applicaton 
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partititon and contains the offset of the 
Partition Descriptor. Also see Partition 
Descriptor. 

Extension File Header Blocks. An Extension File 
Header Block is required for each file that 
contains more than 32 Disk Extents. Also see 
File Header Block. 

External Interrupt. An external interrupt is 
caused by conditions that are external to the 
8086 processor and are asynchronous to the 
execution of processor instructions. There are 
two kinds of external interrupts: maskable and 
nonmaskable. Also see Internal Interrupt, 
Maskable Interrupt, and Nonmaskable Interrupt. 

FAB. See File Area Block. 

FALSE. FALSE is represented in a flag variable 
as 0. 

FCB. See File Control Block. 

FHB. See File Header Block. 

FIFO. First in, first out. 

File. A file is a set of related records (on 
disk) treated as a unit. 

File Access Methods. Several file access methods 
augment the capabilities of the file management 
system. The file access methods are object 
module procedures that are located in the 
standard CTOS library and linked to application 
systems as required. They provide buffering and 
use the asynchronous input/ouput capabilities of 
the file management system to automatically 
overlap input/output and computation. Also see 
Direct Access Method, Record Sequential Access 
Method, and Sequential Access Method. 

File Area Block. There is a File Area Block for 
each Disk Extent in an open file. The FAB 
specifies where the sectors are and how many 
there are in the Disk Extent. The FAB is pointed 
to by a File Control Block or another FAB. The 
FAB is memory-resident. Also see Disk Extent. 

File Byte Stream. A file byte stream is a byte 
stream that uses a file on disk. Also see Byte 
Stream, Byte Stream Work Area, Communications 
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Byte Stream, Keyboard Byte Stream, Printer Byte 
Stream, Sequential Access Method, Spooler Byte 
Stream, Video Byte Stream, and X.25 Byte Stream. 

File Control Block. There is a File Control 
Block ( FCB ) for each open file. The FCB contains 
information about the file such as the device on 
which it is located, the user count (that is, how 
many file handles currently refer to this file), 
and the file mode (read or modify). The FCB is 
pointed to by a User Control Block and contains a 
pointer to a chain of File Area Blocks. The FCB 
is memory-resident. 

File Handle. A file handle is a 16-bit integer 
that uniquely identifies an open file. It is 
returned by the OpenFile operation and is used to 
refer to the file in subsequent operations such 
as Read, Write, and DeleteFile. 

File Header Block. There is a File Header Block 
for each file. The FHB of each file contains 
information about that file such as its name, 
password, protection level, the date/time it was 
created, the date/time it was last modified, the 
disk address and size of each of its Disk 
Extents. The FHB is disk-resident and 1 sector 
in size. Also see Extension File Header Block. 

File Password. A file password protects a file 
in a directory on a volume. 

File Protection Level. A file protection level 
specifies the access allowed to a file when the 
accessing process does not present a valid volume 
or directory password. 

Filename. (File name) A filename is the fourth 
element of a full file specification. 

Filter Process (User-defined) . A user-defined 
filter process is a user-written system service 
process that is included in the System Image at 
system build. A filter process is interposed 
between a client process and a system service 
process that believe they are communicating 
directly with each other. The Service Exchange 
Table is adjusted at system build to route 
requests through the desired filter process. 
Also see Service Exchange Table. 

Filter Process (Local File System) . See Local 
File System. 
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Font. A font is a bit array for each of the 256 
characters in the character set that defines the 
representation of each character when displayed 
on the video display. 

Font RAM. The font RAM, part of the video 
hardware of IWS and MWS workstations, contains a 

10 by 15 bit array for each of the 256 characters 
in the character set. The font RAM can be 
modified under software control. Also see Font 
ROM. 

Font ROM. The font ROM, part of the video 
hardware of an AWS workstation, contains a 9 by 

11 bit array for each of the 256 characters in 
the character set. Also see Font RAM. 

Frame. A frame is a separate, rectangular area 
of the screen. A frame can have any desired 
width and height (up to those of the entire 
screen) . 

Frame Descriptor. A frame descriptor is a 
component of the Video Control Block and contains 
all information about one of the frames. The 
number of frame descriptors in the Video Control 
Block is specified at system build. Also see 
Video Control Block. 

Full File Specification. A full file 
specification consists of a node (node name), 
volname (volume name), dirname (directory name), 
and a filename (file name). 

Hashing Techniques. See Randomization 
Techniques . 

Image Mode. Image mode is one of three printing 
options in printer, printer spooler, and 
communications byte streams. Image mode prints 
the banner page before each file and recognizes 
escape sequences but performs no code 
conversions Also see Normal Mode and Binary 
Mode . 

Indexed Sequential Access Method. The Indexed 
Sequential Access Method (ISAM) provides 
efficient, yet flexible, random access to fixed- 
length records identified by multiple keys stored 
in disk files. See the ISAM Manual . 

Input Byte Stream. See Byte Stream. 
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Integrated Workstation. See IWS Workstation. 

Internal Interrupt. An internal interrupt (often 
called a trap) is caused by and is synchronous 
with the execution of processor instructions. 
The causes of internal interrupts are an 
erroneous divide instruction, the 8086 Trap Flag, 
the INTO (interrupt on overflow) instruction, and 
the INT (interrupt) instruction. Also see 
External Interrupt. 

Interrupt. An interrupt (external or internal) 
is an event that interrupts the sequential 
execution of processor instructions. When an 
interrupt occurs, the current hardware context 
(the state of the hardware registers) is saved. 
This context save is performed partly by the 8086 
processor and partly by the Operating System. 
Also see External Interrupt, Internal Interrupt, 
Maskable Interrupt, Nonmaskable Interrupt, and 
Pseudointerrupt . 

Interrupt Handler. An interrupt handler is a 
locus of computation that is given control when 
an interrupt occurs. Since an interrupt handler 
is not a process, it is permitted to invoke only 
a few specific operations. CTOS interrupt 
handlers are provided for each interrupt type. 
Each interrupt handler services all interrupts of 
a single type. The OS supports two kinds of 
interrupt handlers, mediated and raw. Also see 
Mediated Interrupt Handler and Raw Interrupt 
Handler. 

Interrupt Levels. On IWS workstations, the 8259A 
Programmable Interrupt Controller supports eight 
interrupt levels: 0 - Multibus devices, 1 - SIO 
communications controller, 2 - Multibus devices, 
3 - Programmable Interval Timer, 4 - printer, 
keyboard, Real-Time Clock, and high-speed 
mathematics coprocessor, 5 - Multibus devices, 6 
- Multibus devices, and 7 - disk storage subystem 
(floppy and Winchester). 

Interrupt Type Code. Each potential source of 
interrupt is assigned an interrupt type code (a 
number in the range 0 to 119) that is used to 
vector (direct) the interrupt to the appropriate 
interrupt handler. Also see Interrupt and 
Interrupt Handler. 
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Interrupt Vector Table. The Interrupt Vector 
Table begins at physical memory address 0 and 
contains a 4-byte entry for each interrupt 
type. Each 4-byte entry contains the logical 
memory address (CS:IP) of the first instruction 
to be executed when an interrupt of that type 
occurs. Also see Interrupt Type Code. 

I OB. See I/O Block. 

I/O Block. The I/O Block (IOB) is used by the OS 
as temporary storage during Read, Write, and 
other input /output operations. The IOB contains 
information obtained from the request block. The 
number of IOBs specified at system build must be 
adequate for the maximum number of input/output 
operations that will be in progress 
simultaneously. The IOB is memory-resident. 

IPC. Interprocess Communication. See the 
"Interprocess Communication Management" section. 

ISAM. See Indexed Sequential Access Method. 

ISC. Interstation Communication. See the 
"Interprocess Communication Management" section. 

IWS Workstation. An IWS workstation is a 
Convergent workstation that has standard (or 
optionally advanced) video capabilities and two 
(or optionally five) Multibus slots. Also see 
Advanced Video Capability, AWS Workstation, and 
Standard Video Capability. 

Kernel. The Kernel is the most primitive and the 
most powerful component of the CTOS OS. It 
executes with a higher priority than any process 
but it is not itself a process. The Kernel is 
responsible for the scheduling of process 
execution; it also provides interprocess 
communication primitives. 

Keyboard Byte Stream. A keyboard byte stream is 
a byte stream that uses the keyboard. Also see 
Byte Stream, Byte Stream Work Area, 
Communications Byte Stream, File Byte Stream, 
Printer Byte Stream, Sequential Access Method, 
Spooler Byte Stream, Submit Facility, Video Byte 
Stream, and X.25 Byte Stream. 

Keyboard Code. In unencoded mode, the 8-bit byte 
returned by certain keyboard management 
operations is called a keyboard code. The 
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keyboard code identifies the key in the low-order 
seven bits and indicates the direction of key 
motion in the high-order bit. A 0 indicates key 
depression; 1 indicates key release. Also see 
Unencoded Mode and Appendix C of this Manual . 

Keyboard Encoding Table. The Keyboard Encoding 
Table is used in converting the sequence of 
keyboard codes to 8-bit character codes. The 
Table controls several aspects of the keyboard 
code-to-character-code translation: the 
character code to generate if SHIFT is/is not 
depressed, whether LOCK has the effect of SHIFT 
for this key, whether the key is Typematic 
(repeats), the initial delay before beginning 
Typematic repeating, and the frequency of 
Typematic repeating. The Keyboard Encoding Table 
can be modified dynamically, as well as at system 
build. See the System Programmer ' s Guide for 
detailed information on modifying the Keyboard 
Encoding Table. See Appendix B for the default 
contents of the Keyboard Encoding Table. 

lfa. See Logical File Address. 

Line Attribute. A line attribute controls the 
presentation of a single line. The standard line 
attribute is cursor position. Also see Character 
Attribute, Screen Attribute, and Video 
Attributes . 

Link Block. A link block is a system data 
structure that is used to queue messages at 
exchanges. Each link block contains the address 
of the message and the address of the next link 
block (if any) that is linked onto the 
exchange. Two pools of link blocks are specified 
at system build, a general pool, and a special 
pool used only by the PSend primitive. A call to 
the Request primitive reserves one link block 
from the general pool for the corresponding 
Respond primitive. For these reasons, the number 
of link blocks in each pool can be specified at 
system build. 

Linker. The Linker utility links one or more 
object files into a task image stored in a run 
file. See the Linker/Librarian Manual . 

Local File System. The Local File System allows 
a cluster workstation to access files on local 
mass storage as well as files on mass storage at 
the master workstation. The filter process of 
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the local file system intercepts each file access 
request and directs it to the local file system 
or to the master workstation. 

Local Service Code Table. The Local Service Code 
Table translates each request code to a local 
service code to specify which of the several 
services of the system service process is 
desired. Also see Service Exchange Table. 

Log File. The Log File (the file 
[Sys]<Sys>Log.Sys) is an error-logging file. An 
entry is placed in the Log File for each 
recoverable and nonrecoverable device error . 
This file can be used as a general-purpose 
logging file, for example, to write entries for 
accounting information for system services. 

Logical File Address. A logical file address is 
used to locate a particular sector of a file. An 
lfa specifies the byte position within a file; it 
is the number (the offset) that would be assigned 
to a byte in a file if all the bytes were 
numbered consecutively starting with 0. An lfa 
is a 32-bit unsigned integer that must be on a 
sector boundary and is therefore a multiple of 
512. For example, the lfa of the third sector of 
a file is 1024. 

Logical Memory Address. (usually abbreviated as 
memory address) A logical memory address is a 
32-bit entity that consists of a 16-bit segment 
base address and a 16-bit offset. The physical 
memory address of a byte is computed by 
multiplying the segment base address by 16 and 
adding the offset. A byte of memory does not 
have a unique logical memory address. Rather, 
any of 4096 combinations of segment base address 
and offset refer to the same byte of memory. See 
the chapter on "8086 Machine Organization" in the 
Central Processing Unit for more information. 
Also see Offset, Physical Memory Address, and 
Segment Base Address. 

Long-lived Memory. Long-lived memory is an area 
of memory in an application partition. It is 
used for parameters or data passed from an 
application system to a succeeding application 
system in the same partition. If a character map 
other than the one in the system partition is 
needed, it must be allocated in the long-lived 
memory area of the primary application 
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partition. Also see Application Partitions and 
System Partitions. 

Maskable Interrupt. A maskable interrupt is a 
type of external interrupt. A maskable interrupt 
is given a priority and controlled by the 8259A 
Programmable Interrupt Controller and can be 
masked (ignored) by the use of the processor 
interrupt-enable flag. A maskable interrupt can 
be selectively masked by programming the 8259A 
Programmable Interrupt Controller. Also see 
External Interrupt and Nonmaskable Interrupt. 

Master File Directory. There is an entry for 
each directory on the volume in the Master File 
Directory (MFD), including the Sys Directory. 
The position of an entry within the MFD is 
determined by randomization (hashing) 
techniques. The entry contains the directory's 
name, password, location, and size. The Master 
File Directory is disk-resident. 

Master Workstation. A master workstation is the 
hub of a cluster or minicluster configuration. 
The master workstation provides file system, 
queue management facility, and other services to 
all the cluster workstations. In addition, it 
supports its own interactive and batch 
application systems. Also see Cluster 
Workstation. 

Master Workstation Agent Service Process. The 
Master Workstation Agent Service Process 
reconverts an interstation message to an 
interprocess request and queues it at the 
exchange of the master workstation system service 
process that performs the desired function. Also 
see CWS Agent Service Process. 

Mediated Interrupt Handler. A mediated interrupt 
handler (MIH) is easier to write than a raw 
interrupt handler, permits automatic nesting by 
priority since processor interrupts are enabled 
during its execution, and can communicate its 
results to processes through certain Kernel 
primitives. Also see Interrupt Handler and Raw 
Interrupt Handler. 

Memory Address. See Logical Memory Address. 

Message. A message is the entity transmitted 
between processes by the interprocess 
communication facility. It conveys information 
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and provides synchronization between processes. 
Although only a single 4-byte data item is 
literally communicated between processes, this 
data item is usually the memory address of a 
larger data structure. The larger data structure 
is called the message while the 4-byte data item 
is conventionally called the address of the 
message. The message can be in any part of 
memory that is under the control of the sending 
process. By convention, control of the memory 
that contains the message is passed along with 
the message. 

MFD. See Master File Directory. 

MIH. See Mediated Interrupt Handler. 

Minicluster. A minicluster configuration 
consists of a master workstation and up to four 
cluster workstations. The master workstation 
uses its SIO Channel A rather than a CommlOP to 
connect to the cluster workstations. Also see 
Cluster, Cluster Workstation, and CommlOP. 

Multiprogramming . Multiprogramming is supported 
at three levels by the CTOS OS. First, any 
number of application systems can coexist, each 
in its own partition. Second, any number of 
tasks can be loaded into the memory of the 
partition and independently executed. Third, any 
number of processes can independently execute the 
code of each task. Also see Application System, 
Process, and Task. 

Network. See CT-NET Network. 

NMI. See Nonmaskable Interrupt. 

Node. A node (node name) is the first element of 
a full file specification. A node is also a 
standalone or master workstation that is part of 
a CT-NET Network. 

Nonmaskable Interrupt. A nonmaskable interrupt 
(NMI) is a type of external interrupt. An NMI 
has a higher priority than a maskable 
interrupt. An NMI cannot be masked through the 
use of the processor interrupt-enable flag; 
however, bits in the Input/Output Control 
Register allow each of the four conditions that 
cause NMI to be masked individually. These 
conditions are write-protect violation, 
nonexistent or device-addressed memory parity 
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error, and power failure detection. Also see 
External Interrupt and Maskable Interrupt. 


Nonoverlapped . Nonoverlapped , in the context of 
file access methods, means that a call to an 
access method read or write operation does not 
return to the calling program until all 
associated input or output is complete. 

Normal Mode. Normal Mode is one of three 
printing options in printer, printer spooler, and 
communications byte streams. Normal mode prints 
the banner page before each file, converts tabs 
into spaces and end-of-line characters to device- 
dependent codes, and recognizes the escape 
sequences for manual intervention. Also see 
Binary Mode and Image Mode. 

Notice File. The notice file contains text to be 
printed on banner pages. The notice file is a 
convenient way to convey operational information, 
such as the version of the software currently in 
use, to a later reader of the printed output. 
The notice file ([ Sys] <Sys>Spooler . Notice ) is an 
ordinary text file that can be created and 
modified with the Editor or Word Processor. Also 
see Banner Page. 

Object Module Procedure. An object module 
procedure is a procedure supplied as part of an 
object module file. It is linked with the user- 
written object modules of an application system 
and is not supplied as part of the System 
Image. Most application systems only require a 
subset of these procedures. When the application 
system is linked, the desired procedures are 
linked together in the run file of the 
application. The Sequential Access Method is an 
example of object module procedures. Also see 
System Common Procedure. 

Offset. The offset is the distance, in bytes, of 
the target location from the beginning of the 
hardware segment. Also see Logical Memory 
Address and Physical Memory Address. 

Operation. An operation is a CTOS OS primitive, 
service, or procedure. 

OS. Operating system. 

Output Byte Stream. See Byte Stream. 
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Overlapped. Overlapped, in the context of file 
access methods, means that although the 
application system makes a call to an access 
method read or write operation and that operation 
returns, input/output can continue overlapped 
automatically with the computations of the 
application system. 

Overlay Area. See Swap Buffer. 

Paragraph. A paragraph is 16 bytes of memory 
whose physical memory address is a multiple of 
16. 

Partition Configuration Block. A Partition 
Configuration Block is located in each 
application partition and contains the offsets of 
the Application System Control Block, Batch 
Control Block, and Extended Partition 
Descriptor. Also see Application System Control 
Block, Batch Control Block, and Extended 
Partition Descriptor. 

Partition Descriptor. A Partition Descriptor is 
located in each application partition and 
contains the partition name, the boundaries of 
the partition and of its long- and short-lived 
memory areas, and internal links to partition 
descriptors in other partitions. 

Partition Handle. A Partition Handle is a 16-bit 
integer that uniquely identifies a secondary 
application partition. It is returned by the 
CreatePartition operation and is used to refer to 
the partition in subsequent operations such as 
LoadPrimaryTask, GetPartitionStatus , and 
RemovePartition . 

pb. A pb is the memory address of a string of 
bytes . 

pb/cb. A pb/cb is a 6-byte entity consisting of 
the 4-byte memory address of a byte string 
followed by the 2-byte count of the bytes in that 
byte string. 

PCB. See Process Control Block. 

Physical Mdmory Address. Each byte of memory has 
a unique 20-bit physical memory address. 
Software uses logical memory addresses, not 
physical memory addresses. The physical memory 
address of a byte is computed by multiplying the 
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segment base address by 16 and adding the 
offset. Also see Logical Memory Address, Offset, 
and Segment Base Address. 

Physical Record. A physical record (in the 
context of file access methods) is an entity that 
consists of the record header, the record data, 
and the record trailer stored in contiguous 
bytes . 

PIC. See Programmable Interrupt Controller. 

PIT. See Programmable Interval Timer. 

Primary Application Partition. The primary 
application partition is for interactive programs 
that use the keyboard and video display to 
interact with the user. Such partitions can be 
loaded with interactive programs chosen by the 
user, such as the Editor, Word Processor, or 
terminal emulators. Also see Secondary 
Application Partition. 

Primary Task. The primary task is the first task 
that is loaded into an application partition. It 
is loaded with the LoadPrimaryTask operation by a 
process in the primary application partition, or 
a Chain, Exit, or ErrorExit operation by a 
process in its own partition. The primary task 
in turn can load additional tasks, called 
secondary tasks, in its own partition with the 
LoadTask operation. 

Primitive. A primitive is an operation performed 
by the Kernel. Also see Kernel. 

Printer Byte Stream. A printer byte stream is a 
byte stream that performs direct printing. It 
can use either a Centronics-compatible printer 
connected to a parallel printer port or an 
RS-232C-compatible printer connected to 
communications Channel A or B of the workstation 
on which the application system is executing. 
Also see Byte Stream, Byte Stream Work Area, 
Communications Byte Stream, Direct Printing, File 
Byte Stream, Keyboard Byte Stream, Sequential 
Access Method, Spooled Printing, Spooler Byte 
Stream, Video Byte Stream, and X.25 Byte Stream. 

Printer Spooler. The printer spooler is a 
dynamically installed system service that 
transfers text from disk files to the printer 
interfaces of the workstation on which the 
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printer spooler is installed. It can 
simultaneously control the operation of several 
printers. A disk-based priority-ordered queue 
controlled by the queue manager contains the file 
specifications of the files to be printed and the 
parameters (such as the number of copies and 
whether to delete the file after printing) 
controlling the printing. This allows the 
printer spooler to resume printing automatically 
when reinstalled following a CTOS reload. Also 
see Direct Printing, Printer Byte Stream, Spooled 
Printing, and Spooler Byte Stream. 

Printer Spooler Escape Sequence. Printer spooler 
escape sequences are special character sequences 
embedded in text files. They cause the printer 
to pause when processed by the printer spooler. 
Escape sequences are available to request a forms 
change, a print wheel change, and a generic 
printer pause. The reason for the printer pause 
(including a text string that is included in the 
escape sequence) can be ascertained by the 
Spooler utility. (See the "Printer Spooler 
Utilities Overview" in the System Utilities 
Manual . ) Also see Escape Sequence. 

Printing Mode. See Binary Mode, Image Mode, and 
Normal Mode. 

Procedural Interface. A procedural interface is 
a convenient way to access system services and is 
compatible with FORTRAN and Pascal, as well as 
assembly language. 

Procedure. A procedure is a subroutine. 

Process. A process is the basic entity that 
competes for access to the processor and which 
the CTOS OS schedules for execution. Associated 
with a process is the address (CS:IP) of the next 
instruction to execute on behalf of this process, 
a copy of the data to be loaded into the 
processor registers before control is returned to 
this process, a default response exchange, and a 
stack. A process is assigned a priority when it 
is created so that the OS can schedule its 
execution appropriately. 

Process Context. The context of a process is the 
collection of all information about a process. 
The context has both hardware and software 
components. The hardware context of a process 
consists of values to be loaded into processor 
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registers when the process is scheduled for 
execution. This includes the registers that 
control the location of the process's stack. The 
software context of a process consists of its 
default response exchange and the priority at 
which it is to be scheduled for execution. The 
combined hardware and software context of a 
process is maintained in a system data structure 
called a Process Control Block. Also see Context 
Switch and Process Control Block. 

Process Control Block. The combined hardware and 
software context of a process is maintained in a 
system data structure called a Process Control 
Block. A Process Control Block is the physical 
representation of a process. Also see Process 
Context . 

Processor. A processor consists of the CPU, 
memory, and associated circuitry. In the 
Workstation Hardware Manual , this is referred to 
as the mainframe. Also see CPU. 

Programmable Interrupt Controller. A master 
8259A Programmable Interrupt Controller is 
standard on each workstation in the IWS family 
and controls eight interrupt levels. Each 
interrupt level can be connected (wire ORed) to 
one or more device controllers or to a slave 
8259A. The use of slave 8259As multiplies the 
number of external interrupt sources that can 
have a unique identity and priority. The PIC is 
a very flexible hardware entity that can operate 
in a number of modes. The modes established by 
CTOS initialization are level (not edge) 
triggered, fully (not special fully) nested, 
fixed (not rotating) priority, and not special 
mask mode. Also see Interrupt and Interrupt 
Levels . 

Programmable Interval Timer. The Programmable 
Interval Timer provides high-resolution low- 
overhead activation of user pseudointerrupt 
handlers. AWS workstations do not provide a 
PIT. Also see Real-Time Clock. 

Pseudointerrupt. A pseudointerrupt is 
implemented in software rather than in hardware 
and in this sense is not really an interrupt. 
However, a pseudointerrupt causes an interrupt 
handler to be executed as a real interrupt is and 
has the same responsibilities and privileges. 
Also see Interrupt. 
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Queue Entry. A queue entry is a formatted 
request for processing that is added to the 
specified queue entry file by client processes. 
A queue entry consists of a number of contiguous 
512-byte sectors and has two parts, a control 
part (40 bytes reserved for the queue manager), 
and a type-specific part defined by the user. 
Client and server processes communicate via 
fields within the queue entry. Also see Client 
Process, Queue Entry File, Queue Manager, and 
Server Process. 

Queue Entry File. A queue entry file contains 
entries for a single type of processing such as 
spooled printing, batch processing, or remote job 
entry. Each queue entry file represents a 
priority-ordered, disk-based queue that is 
controlled by the queue manager. Also see Queue 
Manager . 

Queue Entry Handle. A queue entry handle is a 
32-bit integer that uniquely identifies a queue 
entry. It is returned by the MarkKeyedQueue Entry 
and MarkNextQueueEntry operations and used in 
subsequent ReadQueueEntry , RemoveMarked- 
QueueEntry, RewriteMarkedQueueEntry , and 
UnmarkQueueEntry operations. 

Queue Index File. The queue index file is a 
system-wide text file that defines the queues to 
be used in the system. The system manager 
creates the queue index file in the master 
workstation, entering information such as the 
name of each queue, its associated queue entry 
file, the size of its entries, and the type of 
the queue (for example, printer spooler, RJE, or 
batch queue) . 

Queue Manager. The queue manager controls named, 
priority-ordered, disk-based queues contained in 
queue entry files. It must be installed in the 
master workstation, either as a system service in 
the system partition, or in a secondary 
application partition. Also see Queue Entry, 
Queue Entry File, Queue Entry Handle, Queue Index 
File, Queue Status Block, and System Service. 

Queue Status Block The Queue Status Block is in 
the control portion of the queue entry that is 
reserved for the queue manager. It is referenced 
by the MarkKeyedQueueEntry, MarkNextQueueEntry, 
and ReadQueueEntry operations and reports a queue 
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entry's server user number, priority, and the 
buffers in which the queue entry handles for the 
queue entry and the logically following queue 
entry are stored. 

Randomization Techniques. A file entry in a 
directory (or a directory entry in a Master File 
Directory) is located by means of the character 
string that identifies the file (or the 
directory). The character string is converted to 
a pseudorandom number which is then converted to 
the address of the sector where the entry is 
expected to be located. If the entry is not in 
the expected sector, then adjacent sectors are 
searched . 

Raw Interrupt Handler. A raw interrupt handler 
(RIH) provides faster execution than a mediated 
interrupt handler since the entry in the 
Interrupt Vector Table points directly to the 
entry point of the RIH. A RIH is useful for 
servicing a high-speed non-DMA device that causes 
an interrupt whenever a byte is to be 
transferred. Also see Interrupt Handler and 
Mediated Interrupt Handler. 

Ready State. The ready state is one of three 
states in which a process can exist. A process 
is in the ready state when it could be running, 
but a higher priority process is currently 
running. Any number of processes can be in the 
ready state at a time. Also see Running State 
and Waiting State. 

Real-Time Clock. The Real-Time Clock ( RTC ) is 
used by the OS to provide the current date and 
time of day and timing of intervals (in units of 
100 ms). Also see Programmable Interval Timer. 

Record Fragment. A record fragment is a 
contiguous area of memory within a record. A 
record fragment is specified using an offset from 
the beginning of the record and a byte count. 

Record Number. A record number specifies the 
record position relative to the first record in a 
file. The record number of the first record in a 
file access method file is 1. 

Record Sequential Access Method. The Record 
Sequential Access Method (RSAM) provides blocked, 
spanned, overlapped input and output. An RSAM 
file is a sequence of fixed- or variable-length 
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records. Files can be opened for read, write, or 
append operations. Also see Blocked, Record 
Sequential Work Area, and Spanned. 

Record Sequential Work Area. A Record Sequential 
Work Area is a 150-byte memory work area for the 
exclusive use of the Record Sequential Access 
Method procedures. Any number of RSAM files can 
be open simultaneously using separate RSWAs . 
Also see Record Sequential Access Method. 

Recording File. A recording file, a file used in 
recording mode, contains a copy of all characters 
typed at the keyboard while recording mode is 
active. A recording file can later be used as a 
submit file to repeat the same sequence of input 
characters. The use of a recording file and the 
use of a submit file are mutually exclusive. 
Also see Recording Mode and Submit File. 

Recording Mode. When recording mode is active, 
all characters typed at the keyboard and read in 
character mode are written to a recording file, 
in addition to being returned to the client 
process. Also see Recording File. 

Request. A request requests that an operation be 
performed by a system service process. 

Request Block. A request block is a block of 
memory provided by the client process that 
contains highly structured information. (See the 
"Concepts" section.) The memory address of the 
request block is provided by the client process 
during a Request primitive and by the system 
service process during a Respond primitive. A 
request block is the "element" that the 
application system (or the OS) sends to the OS to 
request that a particular operation be performed. 

Request Code. A request code is a unique 16-bit 
integer that is placed in a request block by a 
client process. The request code is used by the 
Request primitive both to route a request to the 
appropriate system service process and to specify 
to that process which of the several services it 
provides is currently requested. Request codes 
are listed in numeric sequence in Appendix D. 

Request Control Block. A Request Control Block 
is an internal data structure. There is one for 
each concurrent request. The number of RCBs is a 
system build parameter. 
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Response Exchange. A response exchange is the 
exchange at which the requesting client process 
waits for the response of a system service. Also 
see Default Response Exchange and Exchange. 

RIH. See Raw Interrupt Handler. 

RSAM. See Record Sequential Access Method. 

RTC. See Real-Time Clock. 

Run File. A run file is created by the Linker 
and contains a task image. Also see Task Image. 

Running State. The runnning state is one of 
three states in which a process can exist. A 
process is in the running state when the 
processor is actually executing its 
instructions. Only one process can be in the 
running state at a time. Also see Ready State 
and Waiting State. 

SAM. See Sequential Access Method. 

SAMGen. See SAM Generation. 

SAM Generation. SAM generation permits the 
specification of the device-dependent object 
modules to be linked to an application system. 
See the System Programmer ' s Guide . 

Screen Attribute. A screen attribute controls 
the presentation of the entire screen. The 
standard screen attributes are blank, reverse 
video (dark characters on a light background), 
half-bright, number of characters per line (80 or 
132), and the presence or absence of character 
attributes. Also see Character Attribute, Line 
Attribute, and Video Attributes. 

Secondary Application Partition. A secondary 
application partition is a memory partition that 
is created and controlled by using operations 
provided by the application partition management 
facility. Such partitions are used for 

noninteractive applications, such as user 
applications, the batch manager, or system 
services including the printer spooler, ISAM, and 
remote job entry. Also see Application 

Partition, Application Partition Management, and 
Primary Application Partition. 
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Secondary Task. A secondary task is a task that 
is loaded by the primary task. Also see Primary 
Task . 


Security Mode. The security mode causes the 
printer spooler to pause before printing a file 
and wait for a password to be entered. 

Segment. A segment is a contiguous (usually 
large) area of memory that consists of an 
integral number of paragraphs. Segments are 
usually classified into one of three types: 
code, static data, or dynamic data. Each kind of 
segment can be either shared or nonshared. Also 
see Code Segment and Data Segment. 

Segment Base Address. A segment base address is 
the high-order 16 bits of the 20-bit physical 
memory address of the first byte of a hardware 
segment. (The low-order 4 bits are implicitly 
0.) The 8086 processor segment registers CS, DS, 
SS, and ES contain segment base addresses. Also 
see Logical Memory Address and Physical Memory 
Address . 

Sequential Access Method. The Sequential Access 
Method provides device-independent access to 
devices (such as the video display, printer, 
files, and keyboard) by emulating a conceptual, 
sequential character-oriented device known as a 
byte stream. Also see Byte Stream, Byte Stream 
Work Area, Communications Byte Stream, File Byte 
Stream, Keyboard Byte Stream, Printer Byte 
Stream, Spooler Byte Stream, Video Byte Stream, 
and X.25 Byte Stream. 

Server Process. A server process (such as the 
printer spooler, remote job entry, and batch 
manager) is a system service that has established 
itself as an active server for a particular 
queue. Also see Queue Entry and Queue Manager. 

Service Exchange. A service exchange is an 
exchange that is assigned to a system service 
process at system build. The system service 
process waits for requests for its services at 
its service exchange. Also see Service Exchange 
Table. 

Service Exchange Table. The Service Exchange 
Table is constructed at system build, resides in 
the System Image, and translates request codes to 
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service exchanges. Also see Local Service Code 
Table and Service Exchange. 

Service Process. See System Service Process. 

Short-lived Memory. Short-lived memory is an 
area of memory in an application partition. When 
a task is loaded, the OS allocates short-lived 
memory to contain its code and data. Short-lived 
memory can also be allocated directly by a client 
process in its own partition. Common uses of 
short-lived memory are input /output buffers and 
the Pascal heap. Also see Application 
Partitions . 

Size. The size of a data item or structure 
always refers to the number of bytes contained. 

Spanned. A record file in which a record can 
begin and end in different physical sectors is 
spanned. Also see Blocked and Record Sequential 
Access Method. 

Spooled Printing. Spooled printing transfers 
text to a disk file for temporary storage and 
queues a request through the queue manager for 
the printer spooler to transfer the text to the 
first available printer interface under control 
of the printer spooler. This facilitates sharing 
of printer's by cluster workstations, as well as 
concurrent interactive computing and printing. 
Spooled printing can be accessed through the 
Sequential Access Method (spooler byte streams) 
and the printer spooler utilities. Also see 
Direct Printing, Printer Byte Stream, and Spooler 
Byte Stream. 

Spooler Byte Stream. A spooler byte stream 
automatically creates a uniquely named disk file 
for temporary text storage. It then transfers 
the text to the disk file and expands the disk 
file as necessary. When the spooler byte stream 
is closed, a request is queued through the queue 
manager to the printer spooler to print the disk 
file and delete it after it is printed. This is 
spooled printing. Also see Byte Stream, Byte 
Stream Work Area, Communications Byte Stream, 
Direct Printing, File Byte Stream, Keyboard Byte 
Stream, Printer Byte Stream, Sequential Access 
Method, Spooled Printing, Video Byte Stream, and 
X.25 Byte Stream. 


Glossary-31 



Standard Character Set. The 256-entry standard 
character set is described in Appendix B. Unless 
requested otherwise, the OS loads the Keyboard 
Encoding Table and the font RAM ( IWS 
workstations) to implement the standard character 
set. On AWS workstations the character set is 
stored in ROM. 

Standard Video Capability. Standard video 
capabilities are provided by the IWS family of 
workstations. These capabilities are 
characterized by a 34-line screen, a software- 
selectable 80- or 132-character line, one cursor 
per line, a 256 character set that can be 
dynamically modified by software, and a screen 
split horizontally and/or vertically into 
multiple frames that can overlap each other. 
Also see Advanced Video Capability, Basic Video 
Capability, and Video Capability. 

Static Data Segment. See Data Segment. 

Status Code. A status code reports the success 
or failure of the requested operation. A status 
code is stored in a request block by the system 
service process and is examined by the client 
process. See Appendix A for a list of status 
codes . 

Style RAM. The style RAM, part of the advanced 
video capability, contains 16 entries, each of 
which specifies the presence or absence of each 
of the video attributes. Entries are selected by 
the 4-bit values in the character attribute 
fields of the character map. 

Submit Facility. The submit facility permits a 
sequence of characters from a file to be sub- 
stituted for characters typed at the keyboard. 
The use of submit files allows the convenient 
repetition of command sequences. Also see Submit 
File. 

Submit File. A submit file, a file used in the 
submit facility, contains the same sequence of 
characters that would be typed to the desired 
programs. When a submit file is activated by a 
request from an application process or a command 
to the Executive, a character from the file is 
returned to the application process whenever it 
requests a character from the keyboard. A 
recording file and a submit file cannot be used 
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simultaneously. Also see Recording File and 
Submit Facility. 

Submit File Escape Sequence. A submit file 
escape sequence consists of two or three 
characters. The first is the code 03h, which 
indicates the presence of an escape sequence. 
The second character of the escape sequence is a 
code to identify the special function. The third 
character, if present, is an argument to the 
function. Also see Escape Sequence and Submit 
File . 

Swap Buffer. The swap buffer is an overlay area 
in the memory of an application partition. The 
swap buffer is used to contain all nonresident 
code segments. This buffer must be large enough 
to contain the largest nonresident code 
segment. A larger buffer permits more code 
segments to be kept in the main memory of the 
partition and improves system performance. Also 
see Virtual Code Segment Swapping. 

SysCntds. The Executive's command file (SysCmds) 
contains information about each command known to 
the Executive. [Sys] <Sys> SysCmds is used if 
there is no SysCmds file in the Application 
System Control Block. The New Command command is 
used to enter additional commands into SysCmds. 

Sys. Font. The [ Sys] < Sys >Sys . Font file contains 
the font for the standard character set. 

System Administrator. See System Manager. 

System Build. System build is the collective 
name for the sequence of actions necessary to 
construct a customized CTOS System Image. System 
build allows the specification of installation- 
specific parameters and the inclusion of user- 
written system services. See the System 
Programmer's Guide for more details. 

System Common Address Table. The System Common 
Address Table contains the 4-byte logical memory 
address of each of a number of CTOS system data 
structures. It starts at physical memory address 
240h. See Appendix E for more information. 

System Common Procedure. A system common 
procedure performs a common system function, such 
as returning the current date and time. The code 
of the system common procedure is included in the 
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System Image and is executed in the same context 
and at the same priority as the invoking 
process. The Video Access Method, for example, 
is a system common procedure. Also see Object 
Module Procedure. 

System Configuration Block. The System 

Configuration Block allows the application system 
to determine detailed information about the 
System Image (workstation configuration and 
system build parameters). See Appendix E for | 

more information. 

System Data Structures. System data structures 
are data areas contained within the OS and 
necessary for its operation. These structures 
are often configuration-dependent. A File 

Control Block and a File Area Block are examples 
of system data structures. 

Sys(tem) Directory. The Sys(tem) Directory of 
each volume contains entries for system files, 
including the Bad Sector File, the File Header 
Blocks, the Master File Directory, the System 
Image, the Crash Dump Area, the Log File, and the 
Executive. The Sys Directory is created by the 
IVolume utility rather than by the CreateDir 
operation. Also see Sys (tern) Volume. 

System Event. A system event affects the 

executability of a process. Examples of system 
events are an interrupt from a device controller, 
Multibus device, timer, or Real-Time Clock, or a 
message sent from another process. The system 

event causes a message to be sent to an exchange 
at which a higher priority process is waiting? 
this, in turn, causes the OS to reallocate the 
processor. Also see Event. 

System Image. The System Image (the file 

[Sys]<Sys>SysImage.Sys) contains a run-file copy 
of the CTOS OS . 

System Manager. The system manager is the person 
responsible for planning, generating, extending, 
and controlling the use of the OS to improve the 
overall productivity of the installation. 

System Memory. System memory is a contiguous 
area of memory beginning at address 0 that is 
permanently reserved for use by the OS. 
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System Partition. A system partition contains 
the CTOS OS or dynamically installed system 
services. Also see Application Partition. 

System Service. A system service is an operation 
performed by a system service process. 

System Service Process. A system service process 
is a CTOS OS process that services and responds 
to requests from client processes. Both 
Convergent- and user-written system service 
processes can be dynamically installed or linked 
to the System Image at system build. A system 
service process is scheduled for execution in the 
same manner that an application process is 
scheduled. Also see Application Process and 
Client Process. 

Sys(tem) Volume. The OS is bootstrapped from the 
Sys(tem) Volume. The Sys(tem) Directory of the 
Sys(tem) Volume contains entries for system files 
that are not necessary in the Sys Directories of 
other volumes. These additional entries must be 
placed in [Sys]<Sys> when the volume is 
initialized. Sys Image . Sys , CrashDump.Sys, and 
Log. Sys are created (but not initialized) by the 
IVolume utility. The other file entries are 
created using the CreateDir operation or the 
Create Directory command. These system files 
are the System Images, the Crash Dump Areas, the 
Log File, the Debugger, the Executive, the 
Executive's command file, and the standard 
character font. Also see Crash Dump Area, 
Executive, Log File, Sys(tem) Directory, and 
System Image . 

Task. A task consists of executable code, data, 
and one or more processes. The code and data can 
be unique to the task or shared with other 
tasks. A task is created by translating source 
programs into object modules and then linking 
them together. This results in a task image that 
is stored on disk in a run file. When requested 
by a currently active task, such as the 
Convergent Executive, the OS reads the task image 
from the run file into the application partition, 
relocates intersegment references, and schedules 
it for execution. The new task can coexist with 
or replace other application tasks. Also see 
Application System, Run File, and Task Image. 

Task Image. A task image is a program stored in 
a run file that contains code segments and/or 
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static data segments. Also see Run File and 
Task. 

Text File. A text file is a file in which each 
byte represents a printable character, or a 
control character such as tab (09h) , new line 
(OAh), or formfeed (OCh). 

Time slicing. Time slicing means that processes 
with the same priority are executed in turn for 
intervals of 100 ms in round robin fashion. 
Processes having priorities within a predefined 
range are subject to time slicing. 

Timer Request Block. The Timer Request Block is 
a data structure shared by the client process and 
timer management. The TRB defines the interval 
after which a message is to be sent to a 
specified exchange. Also see Real-Time Clock. 

Trap. See Internal Interrupt. 

TRB. See Timer Request Block. 

TRUE. TRUE is represented in a flag variable as 
OFFh. 

Type-Ahead Buffer. The type-ahead buffer stores 
keyboard characters (or keyboard codes, if in 
unencoded mode) that have not yet been read by a 
client process. If the workstation operator 
types too many characters in advance of 
processing, the excess characters are 
discarded. When the client process reads beyond 
those characters that were buffered successfully, 
it receives a special status code. The size of 
the type-ahead buffer is usually 128 characters, 
but can be changed at system build. 

UCB. See User Control Block. 

Unencoded Mode. In unencoded mode, the client 
process receives an indication of each key 
depression and release. This mode provides 
maximum flexibility. Also see Character Mode and 
Keyboard Code . 

User Control Block. There is a User Control 
Block (UCB) for each user number. The UCB 
contains the default volume, default directory, 
default password, and default file prefix set by 
the last SetPath and SetPrefix operations. The 
UCB is memory-resident. 
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User File Block. The User File Block contains a 
pointer to the File Control Block for each open 
file . 

User Number. A user number is a 16-bit integer 
that uniquely identifies an application system. 
Each application partition has a different user 
number. Processes in the same application 
partition share the same user number. A process 
obtains its user number with the GetUserNumber 
operation (see the "Process Management" 
section.) In the primary application partition 
of a standalone or master workstation, the user 
number is always 0. 

Utility. A utility is a program designed to 
perform a common task such as comparing the 
contents of two files. IVolume, Backup Volume, 
Restore, Dump, and Maintain File are examples of 
utilities. (See the System Utilities Manual . ) 

VAM. See Video Access Method. 

Variable-Length Parameter Block. The Variable- 
Length Parameter Block (VLPB) is used by the 
Executive or batch manager to communicate 
parameters to a succeeding application system in 
the partition in which the VLPB is located. The 
VLPB is created in the long-lived memory of an 
application partition and its memory address is 
stored in the Application System Control Block. 
Also see Application System Control Block. 

VCB. See Video Control Block. 

VDM. See Video Display Management. 

VHB. See Volume Home Block. 

Video Access Method. The Video Access Method 
provides direct access to the characters and 
attributes of each frame. VAM can put a string 
of characters anywhere in a frame, specify 
character attributes for a string of characters, 
scroll a frame up or down a specified number of 
lines, position a cursor in a frame, and reset a 
frame . 

Video Attributes. Video attributes control the 
visual presentation of characters on the 
screen. There are three kinds of video 
attributes: screen, line, and character. Also 
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see Character Attribute, Line Attribute, and 
Screen Attribute. 

Video Byte Stream. A video byte stream is a byte 
stream that uses the video display. Also see 
Byte Stream, Byte Stream Work Area, 
Communications Byte Stream, File Byte Stream, 
Keyboard Byte Stream, Printer Byte Stream, 
Sequential Access Method, Spooler Byte Stream, 
and X.25 Byte Stream. 

Video Capability. The several models of 
workstation have varying levels of video 
capability: basic, standard, or advanced. Also 
see Advanced Video Capability, Basic Video 
Capability, and Standard Video Capability. 

Video Control Block. The Video Control Block 
contains all information known about the video 
display, including the location, height, and 
width of each frame, and the coordinates at which 
the next character is to be stored in the frame 
by the Sequential Access Method. The VCB is 
located in CTOS memory at an address recorded in 
the System Common Address Table. Also see Frame 
Descriptor. 

Video Display Management. Video Display 
Management provides direct control over the video 
hardware. With it, an application system can 
determine the level of video capability, load a 
new character font into the font RAM, change 
screen attributes, stop video refresh, calculate 
the amount of memory needed for the character map 
based on the desired number of columns and lines 
and the presence or absence of character 
attributes, initialize each of the frames, and 
initialize the character map. 

Video Refresh. Video refresh is a hardware 
function that reads (using DMA) characters and 
line and character attributes from the character 
map in memory. It then converts them from the 
extended ASCII (8-bit) memory representation to a 
bit array by accessing the font RAM (or font 
ROM) , and displays these bits on the screen as a 
pattern of illuminated dots (pixels). Also see 
Font RAM and Font ROM. 

Virtual Code Segment Swapping. Virtual code 
segment swapping is the method of virtual memory 
supported by the CTOS OS. The code of each task 
is divided into variable-length segments that 
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reside on disk in a run file. As the task 
executes, only those code segments that are 
required at a particular time actually reside in 
the main memory of the application partition; the 
other code segments remain on disk until they, in 
turn, are required. When a particular code seg- 
ment is no longer required, it is simply overlaid 
by another code segment. Also see Code Segment 
and Virtual Memory. 

Virtual Memory. Virtual memory is a technique 
that makes the apparent size of memory in an 
application partition (from the perspective of 
the application programmer) greater than its 
physical size. The primary mechanisms for the 
implementation of virtual memory are page 
swapping and segment swapping. The CTOS OS 
supports virtual code segment swapping. (The use 
of program overlays is not considered virtual 
memory because it is not transparent to the 
application programmer.) Also see Virtual Code 
Segment Swapping. 

VLPB. See Variable-Length Parameter Block. 

Volname. (Volume name) A volname is the second 
element of a full file specification. 

Volume. A volume is the medium of a disk drive 
that was formatted and initialized with a volume 
name, a password, and volume control structures 
such as the Volume Home Block, the File Header 
Blocks, the Master File Directory, etc. A floppy 
disk and the medium sealed inside a Winchester 
disk are examples of volumes. 

Volume Control Structures. Volume control 
structures allow the file management system to 
manage (allocate, deallocate, locate, avoid 
duplication of) the space on the volume not 
already allocated to the volume control 
structures themselves. A volume contains a 
number of volume control structures; the Volume 
Home Block, the File Header Blocks, the Master 
File Directory, and the Allocation Bit Map, among 
others . 

Volume Home Block. There is a Volume Home Block 
for each volume. The VHB is the root structure 
(that is, the starting point for the tree 
structure) of information on a disk volume. The 
VHB contains information about the volume such as 
its name and the date it was created. The VHB 
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also contains pointers to the Log File, the 
System Image, the Crash Dump Area, the Allocation 
Bit Map, the Master File Directory, and the File 
Header Blocks. The VHB is disk-resident and 1 
sector in size. 

Volume Password. A volume password protects a 
volume . 

Waiting State. The waiting state is one of three 
states in which a process can exist. A process 
is in the waiting state when it is waiting at an 
exchange for a message. A process enters the 
waiting state when it must synchronize with other 
processes. A process can only enter the waiting 
state by voluntarily issuing a Wait Kernel 
primitive that specifies an exchange at which no 
messages are currently queued. The process 
remains in the waiting state until another 
process (or interrupt handler) issues a Send (or 
PSend, Request, or Respond) Kernel primitive that 
specifies the same exchange that was specified by 
the Wait primitive. Any number of processes can 
be in the waiting state at a time. Also see 
Ready State and Running State. 

Write— Behind Mode. In write-behind mode, the 
Direct Access Method writes changed sectors of 
the buffer to disk only when new sectors are 
brought into the buffer, the Direct Access Method 
file is closed, or the mode is changed to write- 
through. Write-behind mode provides better 
performance when the Direct Access Method is used 
to modify records in sequential order. Also see 
Buffer Management Modes and Write-Through Mode. 

Write-Through Mode. In write-through mode, the 
Direct Access Method immediately writes the 
changed sectors of the buffer to disk whenever a 
record is written or deleted. The Direct Access 
Method guarantees that the file content on disk 
is accurate at the completion of a modify 
operation. Also see Buffer Management Modes and 
Write-Behind Mode. 

X.25 Byte Stream. An X.25 byte stream is a byte 
stream that enables data transmission via the 
X.25 network gateway. Each open X.25 byte stream 
corresponds to a virtual circuit that is initiat- 
ed when the byte stream is opened and cleared 
when the byte stream is closed. Also see Byte 
Stream, Byte Stream Work Area, Communications 
Byte Stream, File Byte Stream, Keyboard Byte 
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Stream, 

Method, 


Printer Byte Stream, Sequential Access 
and Video Byte Stream. 
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1 / 14-17 
! Sys , 14-7 

$ Directories, 14-68 
< > (directory name), 14-8 
<$>, see $ Directories 
{ } (node name), 14-8 
[ ] (device specification), 17-2 
[ ] (volume name), 14-8 
[Comm] , 17-4 
[Kbd] , 17-2 
[Lpt] , 17-3 
[Nul] , 17-5 
[Ptr] , 17-3 
[Spl] , 17-4 
[Sys] <$> , 14-69 
[Sys] <Sys>CrashDump. Sys , 30-3 
[Sys] <Sys>Log.Sys, 30-1, 30-5 
[Sys] <Sys>Queue. Index, 15-5, also see 
Queue index file 
[Vid] , 17-5 
[X25] , 17-4 


8048 microprocessor, 26-1 

8085 bootstrap- ROM program, 1 1-2 

8085 microprocessor, 11-1 

8086 CPU, F-8 

8086 processor, 29-1 
8259A Programmable Interrupt 
Controller, 29-5 


Abbreviated specification, 14-8 
Access methods, 16-1 
ACTION- A, 26-8 
ACTION-B, 26-8 
Action code, 26-8 

ReadActionCode service, 26-21 
ACTION- FI NISH, 26-7 

DisableActionFinish service, 26-17 
ACTION key, 26-7 

AddQueueEntry service, 15-9, 15-16 
Address 

logical, 6-2 
physical, 6-2 
segment base, 6-2 
Advanced video capability, 23-5 
LoadCursorRam service, 24-11 
LoadFontRam service, 24-12 
LoadStyleRam service, 24-14 


Agent Service Process 

cluster workstation, 4-23 
master workstation, 4-23 
AllocAllMemorySL service, 6-11 
Allocation Bit Map, 14-61 
AllocExch service, 5-4 
AllocMemoryLL service, 6-13 
AllocMemorySL service, 6-14 
Alphanumeric information, 23-1 
video management, 23-1 
Append mode 

OpenRsFile procedure, 18-7 
Application partition, 10-2 
creating 

CreatePartition service, 10-14 
dynamically, 10-6 
system initialization, 10-6 
data structures, 10-9 

Application System Control Block, 
10-11 

Batch Control Block, 10-11 
Extended Partition Descriptor, 
10-10 

Extended User Control Block, 10-9 
Partition Conf iguration Block, 
10-10 

Partition Descriptor, T0-9 
dynamic control, 10-3 
exchange number 

GetPartitionEx change service, 
10-16 

SetPartitionEx change service, 
10-23 

exit run file, 10-7 
loading, 10-6 
locking 

SetPartitionLock service, 

10-24 

memory organization, 10-4 
partition handle, 10-6 

GetPartitionHandle service, 10-17 
primary task, 10-6 

LoadPrimaryTask service, 10-20 
removing, 10-8 

RemovePartition service, 10-22 
secondary tasks, 10-7 
status, 10-7 

GetPartitionStatus service, 10-18 
system resource deallocating, 10-9 
terminating tasks, 10-8 
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Application partition (cont.) 

TerminatePartitionTasks service, 
10-25 

user number, 14-70 
vacant, 10-8 
vacating tasks 

VacatePartition service, 10-26 
Application partition data 
structures, E-7 

Application partition management, 

10-1 

Application partitions 

communication between, 10-7 
Application system, 7-1, 7-2 
exit run file, 7-4 
replacing 

Chain service, 7-7 
SetlntHandler service, 29-19 
status code, 7-4 
task, 7-2 
task image, 7-2 
terminating, 7-4 

ErrorExit procedure, 7-10 
Exit procedure, 7-12 
Application System Control Block, 

9-4, 10-11 
address, 9-4 

GetpASCB procedure, 9-12 
ResetVideo service, 24-17 
Application System Control Block 
format, 9-5 
Argument passing, F-1 
ASCB, see Application System Control 
Block 

Assembly language access to OS, F-1 
Assembly language conventions, F-1 
Asynchronous conditions, 29-5 
Asynchronous mode, 27-1 
Asynchronous operation, 16-1 
Asynchronous Terminal Emulator, 
Glossary-2 

ATE, see Asynchronous Terminal 
Emulator 
Audio tone 

Beep service, 26-15 
Automatic Volume Recognition, 21-9, 
21-15 

AWS workstation 

basic video capability, 23-6 
AWS 

QueryVidHdw service, 24-15 


Background partition, see Secondary 
application partition 
Backup Volume utility, 14-64 
BadBlk.Sys, 14-66, also see Bad 
Sector File 

Bad Sector File, 14-61, 14-66 
Banner page, 22-2 
Bar chart, B-9 

Basic video capability, 23-6 
character attributes, 23-6 
character map, 23-6 
screen attributes, 23-6 
Batch Control Block, 10-11, E-7 
Batch Control Block format, E-8 
Batch data structure, E-7 
Batch job, Glossary-3 
Batch manager, 1-7 
Batch processing, 15-1 
Beep service, 26-15 
Binary key 

Indexed Sequential Access Method, 
20-2 

Binary mode 

printer byte stream, 17-7 
SetlmageMode procedure, 17-33 
spooler byte stream, 17-8 
Bit-synchronous mode, 27-1 
Blank character, 17-17 
Blink, 17-13 
Blinking, 23-5 

PutFrameAttrs procedure, 25-5 
Block splitting, 20-3 
Bold character, 23-5 
Boolean, F-1 
FALSE, F-1 
TRUE, F-1 

Bootstrap, Glossary-4 
BP Register, F-2 
bsKbd, 17-2 
bsVid, 17-2 

BSWA, see Byte Stream Work Area 

B-tree, 20-3 

Buffer 

Direct Access Method, 19-2 
file access methods, 16-1 
Record Sequential Access Method, 
18-2 

Buffer management 

Direct Access Method, 19-3 
Byte arguments, F-1 
Byte stream, 17-2 
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Byte stream (cont.) 
access 

CloseByteStream procedure, 17-22 
OpenByteStream procedure, 17-24 
checkpointing 

CheckpointBs procedure, 17-21 
communications, 17-9 
file, 17-6 
file address 

GetBsLfa procedure, 17-23 
SetBsLfa procedure, 17-32 
input, 17-2 

ReadBsRecord procedure, 17-28 
ReadByte procedure, 17-29 
ReadBytes procedure, 17-30 
keyboard, 17-8 
output, 17-2 

WriteBsRecord procedure, 17-34 
WriteByte procedure, 17-35 
predefined, 17-2 
printer, 17-6 

direct printing, 17-6 
printing modes, 17-7 
printing mode 

SetlmageMode procedure, 17-33 
releasing 

ReleaseByteStream procedure, 

17-31 
return byte 

PutBackByte procedure, 17-26 
spooler, 17-7 

printing modes, 17-8 
video, 17-10 

QueryVidBs procedure, 17-27 
special characters, 17-10 
X.25, 17-9 

Byte Stream Work Area, 17-2 
Byte string key 

Indexed Sequential Access Method, 
20-2 


CANCEL key, 17-8, 17-15 
Centronics-compatible printer, 17-3 
Chain service, 7-7 
ChangeFileLength service, 14-23 
ChangePriority primitive, 3-8 
Character attributes, 17-13, 23-5, 
23-6 

blink, 17-13 
half-bright, 17-13 
PutFrameAttrs procedure, 25-4 
reverse, 17-13 


underline, 17-13 
Character code, 26-7 

ReadKbdDirect service, 26-23 
Character font 
standard, 14-68 
Sys.Font, 14-68 
Character map, 23-4, 23-6 

basic video capability, 23-6 
InitCharMap service, 24-5 
QueryFrameChar procedure, 25-7 
standard video capability, 23-4 
Character mode, 26-2, 26-7, B-1 

SetKbdUnencodedMode service, 26-26 
Character set 

standard, 26-9, B-1 

graphic representation, B-10 
Character string key 

Indexed Sequential Access Method, 
20-2 

Character-synchronous mode, 27-1 
CheckpointBs procedure, 17-21 
CheckpointRsFile procedure, 18-4 
CheckpointSysIn service, 26-16 
Check primitive, 4-27 
CheckReadAsync procedure, 14-24, 21-6 
CheckWriteAsync procedure, 14-25, 

21-7 

CISR, see Communications Interrupt 
Service Routines 
Classes, F— 1 , F-3 
ClearPath service, 14-26 
Client process, 4-11 

queue management facility, 15-3 
Client-system service 
processing flow, 4-15 
CloseAllFiles service, 14-27 
CloseAllFilesLL service, 14-28 
CloseByteStream procedure, 17-22 
CloseDaFile procedure, 19-6 
CloseFile service, 14-29, 21-8 
CloseRsFile procedure, 18-5 
CloseRTClock service, 28-12 
Cluster configuration, 2-24, 2-27 
cluster workstation, 1-4 
concurrency, 2-27 
IPC facility, 1-4 
master workstation, 1-4 
queue management facility, 15-1 
RS-422 channel, 1-4 
System Configuration Block, E-4 
user-written software, 2-27 
Cluster management, 11-1 
CommlOP, 11-1 


Index-3 



Cluster management (cont.) 

communications I/O processors, 11-1 
communications processor, 11-1 
communications status buffer, 11-9 
DisableCluster service, 11-6 
GetClusterStatus service, 11-8 
GetWSUserName service, 11-12 
RS-422 channel, 11-1 
SetWSUserName service, 11-13 
ws Status block, 11-10 
Clusters, see Cluster configuration 
Cluster workstation, 2-24, 4-23, 14-7 
! Sys , 14-7, 2-24 
$ Directories, 14-69 
CWS Agent Service Process, 4-23 
local file system, 14-17 
QueryWSNum service, 14-44 
Sys, 14-7 

System Image, 14-67 
User Control Block, 14-71 
volume name, 14-7 
workstation type, 14-67 
WS > Sys Image .Sys , 14-67 
W Snnn> Sys Image. Sys, 14-67 
COBOL COMP-3 key 

Indexed Sequential Access Method, 
20-2 

COBOL Relative I-O, 19-1 
CODE key, 26-2, B-1 
Code segment, 6-3 
Collating sequence, 20-2 
Command Interpreter, 1-7 
CommlOP, 11-2 

initialization, 11-2 
initialization control block, 11-2 
operation, 11-3 
status, 11-3 

System Configuration Block, E-14 
CommlOP handler, 11-2 
Common memory pool, 6-5 
Communication between processes, 2-15 
Communications Channel, 17-4 
[Comm] , 17-4 

Communications controller, 27-1 
Communications interrupt handler, 

29-9 

Communications Interrupt Service 
Routine, 11-3, 27-1, 29-13 
ResetCommISR service, 29-16 
SetCommISR service, 29-17 
Communications I/O processors, 11-1 
Communications processor, 11-1 


Communications status buffer format, 
1 1-9 

Concurrency, 16-1 

cluster workstation, 2-27 
Concurrency control, 21-2 
Conf igureSpooler service 

spooler configuration, 22-5 
Context switch, 3-2 
Contingency, Glossary-7 
Contingency management, 30-1 
Convergent date/time format, 28-2 
CompactDateTime procedure, 28-13 
ExpandDateTime procedure, 28-15 
GetDateTime service, 28-16 
SetDateTime service, 28-19 
Convergent date/time structure, 28-2 
Conversion to mediated interrupt 
handler, F-14 
ConvertToSys service, 13-7 
CParams procedure, 9-10 
CPU, Glossary-7 
Crash Dump Area, 14-68 
CrashDump.Sys , 14-68 
Crash procedure, 30-3 
WS>CrashDump.Sys, 14-68 
W Snnn> CrashDump. Sys , 14-68 
CrashDump.Sys, 14-68 
Crash procedure, 30-3 
Create Configuration File utility, 
17-3 

CreateDir service, 14-30 
CreateFile service, 14-15, 14-32 
CreatePartition service, 10-14 
CreateProcess primitive, 3-9 
CSubParams procedure, 9-11 
CT, Glossary-7 
Ct-NET Network, 1-5 
CTOS, Glossary-8 
CTOS components, 2-1 
device handlers, 2-1 
interrupt handlers, 2-1 
Kernel, 2-1 

object module procedures, 2-1 
system common procedures, 2-1 
system service processes, 2-1 
Cursor, 23-9 

PosFrameCursor procedure, 25-3 
ResetFrame procedure, 25-8 
Cursor positioning, 17-14 
Cursor RAM, 23-5 

LoadCursorRam service, 24-11 
Customizing SAM, 17-6 
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CWS, see Cluster workstation 
CWS Agent Service Process, 4-23 


DAM, see Direct Access Method 
Data segment, 6-3 
Data Set 

Indexed Sequential Access Method, 
16-2 

Data store file 

Indexed Sequential Access Method, 
20-3 

Sequential Access Method, 20-3 
Date/time 

GetFileStatus service, 14-37 
SetFileStatus service, 14-53 
Date/time format 
Convergent, 28-2 
expanded, 28-3 
System, 28-3 

Date/time format conversion, 28-4 
DAWA, see Direct Access Work Area 
DCB, see Device Control Block 
Deallocation 

system resource, 10-9 
DeallocExch service, 5-5 
DeallocMemoryLL service, 6-15 
DeallocMemorySL service, 6-16 
Debugger, F-2 

Chain service, 7-9 
FatalError procedure, 30-4 
Default password, 14-10 
Default response exchange, 4-10, 4-12 
Default specification, 14-8 
Defective disk access, 14-14 
Delay procedure, 28-14 
DeleteDaRecord procedure, 19-7 
DeleteDir service, 14-34 
DeleteFile service, 14-35 
Density 

floppy disk, 21-1 
Device 

[Nul] , 17-5 

Device Control Block, 14-71 
null, 17-5 

Sequential Access Method, 17-1 
Device Control Block, 14-71 
GetFileStatus service, 14-37 
QueryDCB service, 21-19 
Device Control Block format, 14-72 
Device/file specification, 17-3 
Device handler, 1-6, 2-2, 29-2, 29-6, 
29-7 


Device-independent access, 17-1 
Device-level access, 21-1 
Device name, 21-3 
Device password, 21-2 
Device specification, 21-2 
Devname, 21-2, also see Device name 
DGroup, F-3 

System Image, E-2 
Direct access 

system service, 4-11 
Direct Access Method, 16-2, 19-1 
buffer, 19-2 
buffer management, 19-3 
cache, 19-1 

COBOL Relative 1-0, 19-1 
data store file, 20-3 
Direct Access Work Area, 19-2 
file 
access 

CloseDaFile procedure, 19-6 
OpenDaFile procedure, 19-8 
input 

ReadDaFragment procedure, 19-12 
ReadDaRecord procedure, 19-13 
output 

WriteDaFragment procedure, 

19-16 

WriteDaRecord procedure, 19-17 
truncating 

TruncateDaFile procedure, 19-15 
file header 

standard, 16-7 

GetStamFileHeader procedure, 16-11 
Maintain File utility, 16-4 
random access, 16-2 
record 
deleting 

DeleteDaRecord procedure, 19-7 
record fragment, 19-2 
record header 
standard, 16-5 
record number, 19-2 

QueryDaLastRecord procedure, 

19-10 

Record Sequential Access Method 
hybrid access, 16-3 
record status 

QueryDaRecordStatus procedure, 
19-11 

record trailer 
standard, 16-7 
sequential access, 19-3 
write-behind mode, 19-3 


Index-5 



Direct Access Method (cont.) 

write-through mode, 19-3 
Direct Access Method buffer 

SetDaBuf ferMode procedure, 19-14 
Direct Access Work Area, 19-2 
Directories, $, see $ Directories 
Directory, 14-5 

Clear Path service, 14-26 
CreateDir service, 14-30 
DeleteDir service, 14-34 
Master File Directory, 14-65 
ReadDirSector service, 14-48 
RenameFile service, 14-50 
SetPath service, 14-55 
Directory lookup, 14-8 
Directory name, 14-7 
Directory password, 14-9 
Directory specification, 14-8 
abbreviated, 14-8 
default, 14-8 
Direct printing, 22-1 
Dirname, see Directory name 
DisableActionFinish service, 26-17 
Di sab leC luster service, 11-6 
Disk access 

CloseFile service, 21-8 
OpenFile service, 21-17 
Disk arm movement 

Volume Home Block, 14-60 
Disk device, 21-2 
Disk error 

ScanToGoodRsRecord procedure, 18-11 
Disk Extent, 14-61 
Disk input 

CheckReadAsync procedure, 21-6 
ReadAsync procedure, 21-23 
Read service, 21-21 
Disk input/output 

Format service, 21-11 
Disk management, 21-1 
Disk output 

CheckWriteAsync procedure, 21-7 
WriteAsynch procedure, 21-29 
Write operation, 21-27 
Disk sector, 14-61 

Allocation Bit Map, 14-61 
Bad Sector File, 14-61 
Disk Extent, 14-61 
Disk volume, 14-60 

IVolume utility, 14-60 
initialization, 14-60 
DismountVolume service, 21-9 
Divide, 29-8 


Double-height line, 23-5 
Double-width line, 23-5 
Doubleword, F-2 
Dynamic data segment 6-3 

End of file, 17-2 
End-of-f ile 

GetFileStatus service, 14-37 
ChangeFileLength service, 14-23 
SetFileStatus service, 14-53 
End-of-Interrupt, 29— 1 1 
EOI , see End-of-Interrupt 
Epilogue, F-2 
Erase, 17-17 

ErrorExit procedure, 7-10 
Escape Sequence 
multibyte, 17-10 
permitted codes, 26-11 
read-direct, 26-12 
submit file, 26-4, 26-11 
video byte stream multibyte, 26-11 
video byte streams, 17-12 
EstablishQueueServer service, 15-12, 
15-18 

Events, 29-1 

continuous count, 28-7 
Exact match, 20-3 
Exchange , 5-2 
allocation, 5-2 

AllocExch service, 5-4 
deallocation, 5-2 

DeallocExch service, 5-5 
identification, 5-2 

QueryDef aultRespExch procedure, 
5-6 

relationship to message, 4-7 
relationship to process, 4-7 
Exchange management, 5-1 
Exchange number 

GetPartitionExchange service, 10-16 
SetPartitionExchange service, 10-23 
Executive, 1-7, Glossary-11 
Exit procedure, 7-12 
Exit run file, 7-4, 10-7 
determining, 7-4 
establishing 

SetExitRunFile service, 7-17 
loading additional tasks, 7-4 
primary task, 7-4 
QueryExitRunFile service, 7-15 
specifying, 7-4 

TerminatePartitionTas :s service, 
10-25 
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ExpandDateTime procedure, 28-15 
Expanded date/time format, 28-3 
CompactDateTime procedure, 28-13 
ExpandDateTime procedure, 28-15 
Expanded date/time structure, 28-4 
Extended Partition Descriptor format, 
10-10, E-8, E-9 

Extended UCB, see Extended User 
Control Block 

Extended system partitions, 2-5 
Extended User Control Block, 10-9 
Extension File Header Block, 14-64 
External interrupts, 29-5 
Extraneous interrupt handler, 29-9 
EXTKN, F-3 


FALSE, Glossary-12 
FatalError procedure, 30-4 
fh, see file handle 
FHB, see File Header Block 
FIFO, Glossary- 12 
File, 14-5, 17-3 
creating, 14-15 
File Header Block, 14-61 
opening, 14-16 
passwords, 14-9 
reading, 14-16 
using, 14-15 
writing, 14-16 
File access 

CloseAllFiles service, 14-27 
CloseFile service, 14-29 
defective disk, 14-14 
DeleteFile service, 14-35 
long-lived 

CloseAllFilesLL service, 14-28 
OpenFileLL service, 14-42 
OpenFile service, 14-40 
random, 14-14 

File access methods, 16-1, 16-2 
Direct Access Method, 16-2 
hybrid access patterns, 16-3 
Indexed Sequential Access Method, 
16-2 

Record Sequential Access Method, 
16-2 

Sequential Access Method, 16-2 
standard CTOS library, 16-1 
File access modes 

modify (exclusive), 1-6 
read (shared), 1-6 


File allocation 

CreateFile service, 14-32 
File handle, 14-14 

GetFhLongevity service, 14-36 
long-lived, 14-14 
OpenFile service, 14-40 
OpenFileLL service, 14-42 
short-lived, 14-14 

SetFhLongevity service, 14-52 
File header 

GetStamFileHeader procedure, 16-11 
standard, 16-7 

File Header Block, 14-61, 14-66 
Disk Extent, 14-61 

extension File Header Blocks, 14-64 
GetFileStatus service, 14-37 
SetFileStatus service, 14-53 
File Header Block format, 14-64 
File header format, 16-8 
FileHeaders . Sys , 14-66, also see File 
Header Blocks 
File input/output 

CheckReadAsync procedure, 14-24 
CheckWriteAsync procedure, 14-25 
ReadAsync procedure, 14-47 
Read service, 14-45 
WriteAsync procedure, 14-59 
Write service, 14-57 
File length 

ChangeFileLength service, 14-23 
GetFileStatus service, 14-37 
File management, 14-1 

volume control structures, 14-60 
Filename 

File Header Block, 14-61 
File name, 14-7 

RenameFile service, 14-50 
File password, 14-10 

SpoolerPassword service, 22-7 
File prefix 

ClearPath service, 14-26 
default 

SetPrefix service, 14-56 
SetPath service, 14-55 
File protection level, 14-11 
access password, 14-11 
access protected, 14-11 
CreateDir operation, 14-11 
decimal values, 14-12 
default, 14-11 

GetFileStatus service, 14-37 
modify password, 14-11 
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File protection level (cont.) 
modify protected, 14-11 
nondirectory access password, 14-11 
nondirectory modify, 14-11 
read password, 14-11 
SetFileStatus operation, 14-11 
SetFileStatus service, 14-53 
unprotected level, 14-11 
File specification 
abbreviated , 14-8 
default, 14-8 
full, 14-8, 17-3 
File status 

GetFileStatus service, 14-37 
File type 

GetFileStatus service, 14-37 
SetFileStatus service, 14-53 
File types 

Indexed Sequential Access Method, 
20-2 

Fill current frame, 17-17 
Filter process 

client-system service interaction, 
4-16 

local file system, 14-17 
system service, 4-15 
Filters, 1-4 
FINISH key, 17-8, 17-16 
Fixed- length record, 16-1, 19-1 
Flags, F— 1 
Floppy disk 
density, 21-1 
formatting, 21-1 
IBM-compatible, 21-1 
non-Convergent 

SetDevParams , 21-25 
sector size, 21-1 
Font RAM, 14-68, 23-5 

LoadFontRam service, 24-12 
Font ROM, 14-68, 23-7 
Format service, 21-11 
Forms-oriented interaction, 25-1, 
also see Parameter management 
Fragmenting, 14-64 
Frame, 17-15, 23-7 

InitVidFrame service, 24-7 
PosFrameCursor procedure, 25-3 
PutFrameAttrs procedure, 25-4 
PutFrameChars procedure, 25-6 
QueryFrameChar procedure, 25-7 
ResetFrame procedure, 25-8 
ScrollFrame procedure, 25-9 
Frame borders 


InitVidFrame service, 24-8 
Frame descriptor, 23-11 
Frame descriptor format, 23-16 
Full brightness 

PutFrameAttrs procedure, 25-4 
Function, F-2 


GetBsLfa procedure, 17-23 
GetClusterStatus service, 11-8 
GetDateTime service, 28-16 
GetFhLongevity service, 14-36 
GetFileStatus service, 14-37 
GetPartitionExchange service, 10-16 
GetPartitionHandle service, 10-17 
GetPartitionStatus service, 10-18 
GetpASCB procedure, 9-12 
GetRsLfa procedure, 18-6 
GetStamFileHeader procedure, 16-11 
GetUCB service, 14-39 
GetUserNumber procedure, 3-12 
GetVHB service, 21-13 
GetWSUserName service, 11-12 
Graphic information, 23-1 
video management, 23-1 
Groups, F-1, F-3 

Half-bright, 17-13, 23-4, 23-5 
PutFrameAttrs procedure, 25-4 
Handle 

file, 14-14 
queue entry, 15-10 
Hardware context, 3-2, 29-1 
Hardware segment, 6-3 
Hashing, 14-65 

Highlight, see Full brightness 
Hybrid access patterns, 16-3 

IBM-compatible floppy disk, 21-1 
Image mode 

printer byte stream, 17-7 
SetlmageMode procedure, 17-33 
spooler byte stream, 17-8 
IMR, see Interrupt Mask Register 
Index 

Indexed Sequential Access Method, 
20-2 

Index file, 16-3 

Indexed Sequential Access Method, 
20-3 
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Indexed Sequential Access Method 
16-2, 20-1 

data store file, 20-3 
Direct Access Method hybrid access, 
16-4 

file header 

standard, 16-7 
file types, 20-2 

GetStamFileHeader procedure, 16-11 
index, 20-2 
key types 

byte string, 20-2 
character string, 20-2 
COBOL COMP-3, 20-2 
long real, 20-2 
packed decimal, 20-2 
short real, 20-2 
keys 

ascending order, 20-2 
collating sequence, 20-2 
descending order, 20-2 
duplicates, 20-2 
inversion, 20-2 
multiuser access, 20-4 
operations, 20-3 
record header 
standard, 16-5 

Record Sequential Access Method 
hybrid access, 16-4 
record trailer 
standard, 16-7 
retrieval 

exact match, 20-3 
prefix match, 20-3 
range match, 20-3 
single-user access, 20-4 
utilities, 20-5 
InitCharMap service, 24-5 
Initial Program Load, see Bootstrap 
Initialization, F-8 
Initialization control block, 1 1-2 
Initialization files, 14-67 
InitOverlays procedure, 8-3, 7 
InitVidFrame service, 24-7 
Input byte stream, 17-2 
Input/Output, 27-3, 27-4 
Direct Access Method, 16-2 
Indexed Sequential Access Method, 
16-2 

Lockln procedure, 27-3 
Lockout procedure, 27-4 
nonoverlapped, 16-2 
overlapped, 16-2 


Record Sequential Access Method, 
16-2 

Sequential Access Method, 16-2 
Input/Output Control Register, 29-7 
Install Queue Manager utility, 15-7 
Interactive partition, see Primary 
application partition 
Internal interrupts, 29-8 
Interpartition communication, 10-7 
exchanges, 10-7 

GetPartitionExchange service, 10-16 
messages, 10-7 

SetPartitionExchange service, 10-23 
SetPartitionLock service, 10-24 
terminating 

application system, 10-8 
Interprocess communication, 4-1 
multitasking capability, 2-14 
communication, 2-14 
resource management, 2-14 
synchronization, 2-14 
Interprocess request to interstation 
message conversion 
request block, 4-24 
Interrupt, 29-1, 29-3 

8259A Programmable Interrupt 
Controller, 29-5 
edge, 29-6 
external, 29-5 
fixed, 29-6 
level, 29-6 
maskable, 29-5 
nested, 29-6 
nesting, 29-3, 29-11 
pseudo, 29-8 
special mask, 29-6 
stack, 29-11 
type code, 29-3 

Interrupt handler, 1-6, 2-2, 29-1, 
29-9 

communications, 29-9 
Communications Interrupt Service 
Routines, 29-13 
dynamically installed system 
service, 29-10 

Extraneous Interrupt Handler, 29-9 
mediated, 29-10 

Printer Interrupt Service Routines, 
29-13 

PSend, 29-10 

PSend primitive, 4-28 

raw, 29-10 

Send primitive, 29-10 
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Interrupt handler packaging, 29-9 
Interrupt handling, F-14 
Interrupt Mask Register, 29-7 
Interrupt Request Register, 29-7 
Interrupt Service Register, 29-7 
Interrupt type code, 29-3 
Interrupt types, 29-4 
Interrupt Vector Table, 29-3 
Interstation communication, 4-23 
CWS Agent Service Process, 4-23 
interprocess communication, 4-23 
master workstation Agent Service 
Process, 4-23 
request message, 4-24 
response message, 4-24 
Interval, 28-5 

Delay procedure, 28-14 
Inversion, 20-2 

I PC, see Interprocess communication 
I PL, see Bootstrap 

IRR, see Interrupt Request Register 
ISAM, see Indexed Sequential Access 
Method 

ISC, see Interstation communication 
ISR, see Interrupt Service Register 
IVolume utility, 14-64, 21-9, 21-11 
IWS 

QueryVidHdw service, 24-15 
Kernel, 2-1 

interprocess communication, 2-1 
process execution scheduling, 2-1 
process synchronization, 2-1 
Key, 16-3 

Indexed Sequential Access Method, 
20-2 

RemoveKeyedQueueEntry, 15-11 
Keyboard, 17-4, 26-6 
[Kbd] , 17-4 
unencoded, 26-1 
Keyboard character 

ReadKbd service, 26-22 
Keyboard code, 26-5, C-1 

ReadKbdDirect service, 26-23 
Keyboard Encoding Table, 26-2, 26-8, 
B-1 

Keyboard management, 26-1 
character mode 
CODE keys , B- 1 
Keyboard modes, 26-1, 26-5 
character, 26-2, 26-7 
unencoded, 26-1, 26-5 


Keyboard/Video Independence, 26-8 
Key types 

binary, 20-2 


LED indicator, 17-18 
LED keys, 26-1,3 

QueryKbdLeds service, 26-18 
SetKbdLed service, 26-25 
If a, see logical file address 
Line attributes, 23-4 
Link block, 4-7 

PSend primitive, 4-28 
Respond primitive, 4-30 
Timer Request Block, 28-5 
Linker/Librarian, F-6 
Linking 

virtual code segment management, 

8-4 

LoadCursorRam service, 24-11 
LoadFontRam service, 24-12 
Loading tasks, 7-3 
LoadPrimaryTask service, 10-20 
LoadStyleRam service, 24-14 
LoadTask service, 7-13 
Local file system, 14-17 
Local resource-sharing networks, 1-4, 
also see Cluster configuration 
Local Service Code Table, 4-21 
Local UCBs , 14-71 
Local variables, F-3 
Lockln procedure, 27-3 
LOCK key, 26-2 
Lockout procedure, 27-4 
Log File, 14-68, 30-1 
Log.Sys, 14-68 
PLog utility, 14-68 
WriteLog service, 30-5 
Logging file, see Log File 
Logical file address, 14-14, F-2 
Logical memory address, see Memory 
address 

Log.Sys, 14-68 
Long-lived memory, 6-5, 9-3 
Long real key 

Indexed Sequential Access Method, 
20-2 


Main CommlOP program, 11-2 
Maintain File utility, 16-4 
Malformed record 

ScanToGoodRsRecord procedure, 18-11 
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MarkKeyedQueueEntry service, 15-12, 
15-20 

MarkNextQueueEntry service, 15-12, 
15-23 

Maskable interrupts, 29-5 
Master File Directory, 14-65, 14-66 
entry format, 14-65 
Sys(tem) Directory, 14-65 
Master workstation, 2-24 
Master workstation Agent Service 
Process, 4-23 

Mediated interrupt handler, 29-10 
conversion to, F-14 
MediatelntHandler primitive, 29-15 
SetlntHandler service, 29-19 
MediatelntHandler primitive, 29-15 
stack, 29-15 
Memory, 

allocation, 6-5 

AllocAllMemorySL service, 6-11 
AllocMemoryLL service, 6-13 
AllocMemorySL service, 6-14 
available size, 

QueryMemAvail service, 6-17 
common memory pool, 6-5 
deallocation, 6-7 

DeallocMemoryLL, 6-15 
DeallocMemorySL service, 6-16 
ResetMemoryLL service, 6-18 
long-lived, 6-5 

AllocMemoryLL, 6-13 
DeallocMemoryLL service, 6-16 
ResetMemoryLL service, 6-18 
uses of, 6-7 
short-lived, 6-5, 6-8 

AllocAllMemorySl service, 6-11 
AllocMemorySL service, 6-14 
DeallocMemorySL service, 6-16 
uses of, 6-8 

Memory address, 6-2, 14-15, F-1 
Memory management , 6- 1 
Memory organization, 6-4 
application partition 
compact system, 6-4 
concurrent application system, 
6-4 

Memory parity error, 29-7 
Message, 4-6 
address, 4-6 

relationship to exchange, 4-7 
relationship to process, 4-7 
sending, 4-8 

sending to another partition, 4-9 


waiting, 4-9 
Message inquiry 

Check primitive, 4-27 
Message transmission 
Send primitive, 4-31 
MFD, see Master File Directory 
Mfd.Sys, 14-66, also see Master File 
Directory 

MIH, see mediated interrupt handler 
Minicluster, Glossary-20 
Mode append, 17-25, 18-7 
Mode modify, 17-25 
Mode read, 17-24, 18-7 
Mode text, 17-24 
Mode write, 17-25, 18-7 
Modify (exclusive) mode, 19-8 
OpenDaFile procedure, 19-8 
OpenFile service, 14-40, 21-17 
OpenFileLL service, 14-42 
Mount Volume service, 21-15 
Multibus, 29-1 

Multibyte escape sequence, 17-12 
Multikey 

Indexed Sequential Access Method, 
16-2 

Multiple frames, 23-2 
Multiprogramming, 1-1 
application system, 1-1 
process, 1-1 
task, 1-1 

Multitasking, see Multiprogramming 
Multiuser access 

Indexed Sequential Access Method, 
20-4 


Name 

directory, 14-7 
file, 14-7 
node, 14-6 
volume, 14-6 
NEXT PAGE key, 17-15 
NMI , see Nonmaskable interrupts 
nnn 

user number, 14-69 
workstation identification, 14-68 
Node name, 14-6 
Nodes, 14-4 

Nonmaskable interrupts, 29-7 
Normal mode 

printer byte stream, 17-7 
SetlmageMode procedure, 17-33 
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Normal mode (cont.) 

SetSysInMode service, 26-27 
spooler byte stream, 17-8 
Null process, 3-4 
Numeric pad, 26-3 

Object module procedure, 2-2 
file access methods, 16-1 
Object modules, F-6 
Offset, 6-2, F— 1 
Open file, 14-14 
OpenByteStream procedure, 17-24 
OpenDaFile procedure, 19-8 
OpenFile service, 14-16, 14-40, 21-17 
OpenFileLL service, 14-42 
OpenRsFile procedure, 18-7 
OpenRTClock service, 28-17 
Operation, Glossary-21 
Output byte stream, 17-2 
Overlapped operation, 16-1 
Overlay area, 8-3 
Overlays , 8-4 
number of, 8-5 
overlaid code, 8-4 
resident code, 8-4 
size, 8-5 
usage, 8-5 


Packed decimal key 

Indexed Sequential Access Method, 
20-2 

Paragraph, 6-2 
Parallel printer 

Printer Interrupt Service Routines, 
29-13 

Parallel printer service routines 
SetLpISR service, 29-21 
Parameter, 9-3 
Parameter creation 

RgParamlnit procedure, 9-14 
RgParamSetEltNext procedure, 9-15 
RgParamSetListStart procedure, 9-16 
RgParamSetSimple procedure, 9-17 
Parameter management, 9-1 

Application System Control Block, 
9-4 

forms-oriented interface, 9-1 
Variable-Length Parameter Block, 

9-3 

Parameter retrieval 

CParams procedure, 9-10 


CSubParams procedure, 9-11 
GetpASCB procedure, 9-12 
RgParam procedure, 9-13 
Partition 

application, 10-2 
primary application, 10-2 
secondary application, 10-2 
system, 10-2 

Partition Configuration Block, 10-10, 
E— 9 

Partition Configuration Block format, 
E-9 

Partition Descriptor, 10-9, E-9 
Partition Descriptor format, E-10 
Partition handle, 10-6 

CreatePartition service, 10-14 
GetPartitionHandle service, 10-17 
Partitions, 10-2 
Partition status, 10-7 

GetPartitionStatus service, 10-18 
Password, 14-9 

Clearpath service, 14-26 
CreateFile, 14-10 
default, 14-10 
device, 21-2 
directory, 14-9 
file, 14-9 

File Header Block, 14-61 
GetFileStatus service, 14-37 
OpenFile , 14-10 
SetFileStatus service, 14-53 
SetPath service, 14-55 
volume, 14-9 
Pause facility, 17-15 
PCB, see Process Control Block 
Physical memory address, 6-2 
Physical record, 16-5 
PISR, see Printer Interrupt Service 
Routines 

PIT, see Programmable Interval Timer 
Pixels, 23-1, 23-5, 23-7 
PLog utility, 14-68, 30-1 
Pointers, F-1 
POP, F— 3 

PosFrameCursor procedure, 25-3 
Power failure detection, 29-7 
Primary application partition, 10-2 
Primary task, 10-6 

LoadPrimaryTask service, 10-20 
Printer 

[Lpt] , 17-3 

Centronics-compatible printer, 17-3 


Index- 1 2 


CTOS" Operating System Manual 


8/82 



Printer (cont.) 
parallel, 17-3 
RS-232-C-compatible, 17-3 
Printer Interrupt Service Routine, 
29-13 

SetLpISR service, 29-21 
Printer spooler, 17-4 
banner page, 22-2 
direct printing, 22-1 
security mode, 22-3 
spooled printing, 22-1 
spooler configuration file, 22-2 
Printer spooler management, 22-1 

Centronics-compatible printer, 22-1 
parallel printer, 22-1 
RS-232-C compatible printer, 22-1 
serial printer, 22-1 
Printing mode 

binary, 17-7, 17-8 
image, 17-7, 17-8 
normal, 17-7, 17-8 
Priority 

ChangePriority primitive, 3-8 
Priority interrupt levels, 29-6 
Procedural access 

system services, 4-10 
Procedural interface 
example, 4-19 
Procedure, 2-2 

object module, 2-2 
system common, 2-2 
Process, 2-4, 3-2 

client-system service interaction, 
4-13 

filter, 4-15 

relationship to application system, 
3-3 

relationship to message, 4-7 
relationship to process, 4-7 
relationship to task, 3-3 
Process context, 29-2 
context switch, 3-2 
hardware, 3-2 
Process Control Block, 3-2 
software, 3-2 

Process Control Block, 3-2, 4-23 
Wait primitive, 4-32 
Process creation 

CreateProcess primitive, 3-9 
Process Descriptor Block 

CreateProcess primitive, 3-10 
Process management, 3-1 


Process number 

QueryProcessNumber procedure, 3-13 
Process priority, 3-3 

ChangePriority primitive, 3-8 
Process scheduling 

event-driven priority, 3-3 
null process, 3-4 
rescheduling, 3-4 
system event, 3-4 
time slicing, 3-4 
Process state, 3-4 
ready, 3-5 
running, 3-5 
waiting, 3-6 

Process state transition, 3-6 
Process suspension 
Wait primitive, 4-32 
Processing flow 

client-system service, 4-15 
Processor architecture, F-1 
Programmable Interval Timer, 28-1, 
28-8, F-14 

ResetTimerlnt primitive, 28-18 
SetTimerlnt primitive, 28-20 
Prologue, F-2 
Protection level 

File Header Block, 14-61 
PSend primitive, 4-28 
Pseudointerrupt handler, 28-8 
Pseudointerrupts, 29-8 
PUBLIC, F— 3 
PUSH, F-3 

PutBackByte procedure, 17-26 
PutFrameAttrs procedure, 25-4 
PutFrameChars procedure, 25-6 


QueryDaLastRecord procedure, 19-10 
QueryDaRecordStatus procedure, 19-11 
QueryDCB service, 21-19 
QueryDefaultRespExch procedure, 5-6 
QueryExitRunFile service, 7-15 
QueryFrameChar procedure, 25-7 
QueryKbdLeds service, 26-18 
QueryKbdState service, 26-19 
QueryMemAvail service, 6-17 
QueryProcessNumber procedure, 3-13 
QueryVidBs procedure, 17-27 
QueryVidHdw service, 24-15 
QueryWSNum service, 14-44 
Queue entry, 15-8 
adding, 15-9 
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Queue entry (cont.) 

AddQueueEntry service, 15-9, 15-16 
MarkKeyedQueueEntry service, 15-20 
MarkNextQueueEntry service, 15-23 
Queue Status Block, 15-10 
reading, 15-9 

ReadKeyedQueueEntry service, 15-25 
ReadNextQueueEntry service, 15-9, 
15-27 

RemoveKeyedQueueEntry service, 
15-11, 15-29 

RemoveMarkedQueueEntry service, 
15-31 

removing, 15-11 

RewriteMarkedQueueEntry service, 
15-32 

sample, 15-13 

UnmarkQueueEntry service, 15-35 
Queue entry file, 15-7 
Queue entry handle, 15-10 
Queue index file, 15-4 
Queue management, 15-1 
Queue management facility 
client process, 15-3 
sequence for using, 15-3 
server process, 15-3 
Queue Manager 

installing, 15-7 

Install Queue Manager utility, 
15-7 

secondary application partition, 
15-7 

system partition, 15-7 
Queue name, 15-5 
Queue server 

EstablishQueueServer service, 15-18 
TerminateQueueServer service, 15-34 
Queue Status Block, 15-10 
Queue Status Block format, 15-10 
Queue type, 15-5 


Random access, 14-14, 16-2, 19-1, 
20-1 

Direct Access Method, 16-2 
Randomization, 14-65 
Range match, 20-3 
Raw interrupt handler, 29-12 

conversion to mediated interrupt 
handler, F-14 

MediatelntHandler primitive, 29-15 
SetlntHandler service, 29-19 


ReadActionCode service, 26-21 
ReadAsync procedure, 14-47, 21-23 
ReadBsRecord procedure, 17-28 
ReadByte procedure, 17-29 
ReadBytes procedure, 17-30 
ReadDaFragment procedure, 19-12 
ReadDaRecord procedure, 19-13 
ReadDirSector service, 14-48 
ReadFile, see Read service 
ReadKbd service, 26-22 
ReadKbdDirect service, 26-23 
ReadKeyedQueueEntry service, 15-25 
Read mode, see Read (shared) mode 
ReadNextQueueEntry service, 15-27 
ReadRsRecord procedure, 18-9 
Read service, 14-45, 21-21 
Read (shared) mode, 19-8 
OpenDaFile procedure, 19-8 
OpenFile service, 14-40, 21-17 
OpenFileLL service, 14-42 
OpenRSFile procedure, 18-7 
Ready state, 3-5 
Real-Time Clock, 28-1, 5 

CloseRTClock service, 28-12 
OpenRTClock service, 28-17 
Real-Time Clock service, 28-17 
Record, 18-2 

blocked, 16-1, 18-1 
Direct Access Method, 16-2 
fixed- length, 16-1, 19-1 
Indexed Sequential Access Method, 
16-2 

overlapped, 18-1 

Record Sequential Access Method, 
16-2 

Sequential Access Method, 16-2 
spanned, 16-1, 18-1 
unstructured byte sequence, 16-1 
variable- length, 16-1, 18-1 
Record fragment 

Direct Access Method, 19-2 
Record header 
standard, 16-5 
Record header format, 16-6 

Universal Record Identifier, 16-6 
Record identifiers, 20-3 
Record number 

Direct Access Method, 19-2 
Record Sequential Access Method, 
16-2, 18-1 
address 

GetRsLfa procedure, 18-6 
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Record Sequential Access Method 
(cont. ) 
buffer, 18-2 

Direct Access Method hybrid access, 

16-3 

file 

access 

CloseRsFile procedure, 18-5 
OpenRsFile procedure, 18-7 
checkpointing 

CheckpointRsFile procedure, 

18-4 

input 

ReadRsRecord procedure, 18-9 
output 

WriteRSRecord procedure, 18-13 
releasing 

ReleaseRsFile procedure, 18-10 
file header 

standard, 16-7 

GetStamFileHeader procedure, 16-11 
Maintain File utility, 16-4 
record, 18-2 
record header 
standard, 16-5 

Record Sequential Work Area, 18-2 
record trailer 
standard, 16-7 
scanning 

ScanToGoodRsRecord procedure, 

18-11 

Record Sequential Work Area, 18-2 
Record trailer format, 16-7 
Record trailer 
standard, 16-7 
Recording file, 26-10 

FatalError procedure, 30-4 
Recording mode, 26-10 

SetSysInMode service, 26-27 
Region, see Application partition 
Register usage, F-1, F-2 
ReleaseByteStream procedure, 17-31 
ReleaseRsFile procedure, 18-10 
Reliability 

Volume Home Block, 14-60 
Remote job entry, 15-1 
Remote UCBs, 14-71 

RemoveKeyedQueueEntry service, 15-29 
RemoveMarkedQueueEntry service, 15-31 
RemovePartition service, 10-22 
RenaraeFile service, 14-50 
Repetitive timing, 28-7 
Request block, 4-16, 4-24 


interprocess request to 
interstation message 
conversion, 4-24 
Request primitive, 4-29 
Respond primitive, 4-30 
Request block header format, 4-17 
Request code, 4-12, 13-2 
ServRq service, 13-8 
Request codes 

in numeric sequence, D-1 
Request data item, 4-18 
Request primitive, 4-21, 4-29, 4-30 
ResetCommISR service, 29-16 
ResetFrame procedure, 25-8 
Res e tMemo ryLL s e r vi ce , 6-18 
ResetTimerlnt primitive, 28-18 
ResetVideo service, 24-17 
Resource management, 2-16 
Response data item, 4-19 
Response exchange, 4-12 
Request primitive, 4-29 
Restore utility, 14-64 
Retrieval 

Indexed Sequential Access Method, 
20-2 

Reverse video, 17-13, 23-4, 23-5 
RewriteMarkedQueueEntry service, 

15-32 

RgParamlnit procedure, 9-14 
RgParam procedure, 9-13 
RgParamSetEltNext procedure, 9-15 
RgParamSetLi st Start procedure, 9-16 
RgParamSetSimple procedure, 9-17 
RIH, see Raw interrupt handler 
RJE, see Remote job entry 
Root structure 

Volume Home Block, 14-61 
RS-232-C-compatible printer, 17-3 
RS-422 channel, 11-1 
RSAM , see Record Sequential Access 

Method 
RSAM file 
address 

GetRsLfa procedure, 18-6 
output 

WriteRsRecord procedure, 18-13 
RSWA, see Record Sequential Work Area 
RTC, see Real-Time Clock 
RTC interrupt handler, 28-5 
Run file, 2-3, 7-2 
exit, 7-4 

Running state, 3-5 
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SAM, see Sequential Access Method 
S AMGen, 17-6 

SAR, see Screen Attribute Register 
ScanToGoodRsRecord procedure, 18-11 
SCAT, see System Common Address Table 
Scheduling, 3-3 
Scr, 14-7 

Scratch volume, 14-7 
Screen Attribute Register, 23-15 
Screen attributes, 17-13, 23-4, 23-6 
half-bright, 17-13 
reverse video, 17-13 
ResetVideo service, 24-17 
SetScreenVidAttr service, 24-19 
ScrollFrame procedure, 25-9 
Scrolling, 23-2, 23-9 
Scrolling control, 17-14 
Secondary application partition, 10-2 
Secondary task, 10-7 
Sector size 

floppy disk, 21-1 
Security mode 

printer spooler, 22-3 
Segment, 6-2, F-1, 3 
code, 6-3 
data, 6-3 
dynamic data, 6-3 
hardware, 6-2 
software, 6-2 
static data, 6-3 
Send primitive, 4-31 
Sequential access, 19-3 
Sequential Access Method, 16-2, 17-1, 
23-9, 27-1, F-4 
byte stream, 17-2 
Byte Stream Work Area, 17-2 
customizing, 17-6 
file header 
standard 

Ope nByteStr earn operation, 17-2 
random access 
files, 17-6 

GETBsLfa, 17-6 
SETBsLfa , 17-6 
record trailer 
standard, 16-7 
Serial input/ output, 27-1 
Serial printer, see 

RS-232-C-compatible printer 
Server process 

queue management facility, 15-3 
Service exchange, 4-12 


Service Exchange Table, 4-21 
Request primitive, 4-29 
ServRq service, 13-8 
SetBsLfa procedure, 17-32 
SetCommISR service, 29-17 
SetDaBuf ferMode procedure, 19-14 
SetDateTime service, 28-19 
SetDevParams service, 21-25 
SetExitRunFile service, 7-17 
SetFhLongevity service, 14-52 
SetFileStatus service, 14-53 
SetlmageMode procedure, 17-33 
SetlntHandler service, 29-19 
SetKbdLed service, 26-25 
SetKbdUnencodedMode service, 26-26 
SetLpISR service, 29-21 
SetPartitionExchange service, 10-23 
SetPartitionLock service, 10-24 
SetPath service, 14-55 
SetPrefix service, 14-56 
SetScreenVidAttr service, 24-19 
SetSysInMode service, 26-27 
SetTimerlnt primitive, 28-20 
SetWSUserName service, 11-13 
SHIFT key, 26-2, B-1 
Short-lived memory, 6-5 
Short real key 

Indexed Sequential Access Method, 
20-2 

Single-user access 

Indexed Sequential Access Method, 
20-4 

SIO, see Serial input/output 
SIO communications controller 

Communications Interrupt Service 
Routines, 29-13 
Lockln procedure, 27-3 
Lockout procedure, 27-4 
ResetCommISR service, 29-16 
SetCommISR service, 29-17 
Software context, 3-2 
Software organization, 2-27 
Software segments, 6-2 
SP, F-2 

Split screen, 23-3 
Spooled printer, 17-4 
Spooled printing, 15-1, 17-7, 22-1 
Spooler configuration 

Conf igureSpooler service, 22-5 
Spooler configuration file, 22-2 
SpoolerPassword service, 22-7 
Spooler utility, 17-4 
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SS, F— 2 
Stack, F— 1 

Media telntHandler primitive, 29-15 
request block, 4-11 
Standalone workstation, 2-24 
Standard character font, 14-68 
Standard cursor, 23-5 
Standard video capability, 23-4 
character attributes, 23-5 
character map, 23-4 
line attributes, 23-4 
LoadFontRam service, 24-12 
screen attributes, 23-4 
Static data segment, 6-3 
Status code 
establishing 

ErrorExit procedure, 7-10 
Exit procedure, 7-12 
Style RAM, 23-6 

LoadStyleRam service, 24-14 
Submit facility, 26-3, 9 
Submit file, 26-3,9 

escape sequence, 26-11 
FatalError procedure, 30-4 
Submit mode 

SetSysInMode service, 26-27 
Subparameter, 9-3 
Subscript, 23-5, B-6 
Superscript, 23-5, B-5 
Swap buffer, 8-3 
allocating, 8-3 
InitOverlays procedure, 8-3 
size, 8-3 
Swapping, 8-2 

InitOverlays procedure, 8-7 
Synchronization, 2-15 
Sys , 1 4-6 

Sys Directory, see Sys (tern) 

Directory 
Sys. Font, 14-68 
Sys Image. Sys, 14-67 
System Image, 14-67 
Sysln, 17-3 
SysOut, 17-3 

System administrator, 15-1 
System build, 2-2, 26-9 

Communications Interrupt Service 
Routines, 29-13 

System Common Address Table, 23-11, 
26-8, 28-3, E-2 
System common procedures, 2-2 
System Configuration Block, E-12 


System Configuration Block format, 
E-12 

System data structures 

Application System Control Block, 

9- 4, 10-11, E-2 

Batch Control Block, 10-11, E-7 
Device Control Block, 14-70 
communications buffer status, 11-9 
Extended Partition Descriptor, 

10- 10, E-8 

Extended User Control Block, 10-9, 
E-8 

File Area Block, 14-70 
File Control Block, 14-70 
file header 

standard, 16-7 

initialization control block, 11-2 
I/O Block, 14-70 
link blocks, 4-7 
Partition Configuration Block, 
10-10, E-9 

Partition Descriptor, 10-9, E-9 
Process Control Block, 3-2 
Process Descriptor Block, 3-9 
Queue Status Block, 15-10 
record header 
standard, 16-5 
record trailer 
standard, 16-7 

System Configuration Block, E-12 
Timer Pseudointerrupt Block, 28-9 
User Control Block, 14-70 
Variable-Length Parameter Block, 

9-3 

Video Control Block, 23-11 
wsStatus block, 11-10 
System date/time format, 28-3 
System date/time structure, 28-3 
Sys(tem) Directory, 14-65 
System directory 

Sys(tem) Volume, 14-67 
system file, 14-66 
System file 

BadBlk.Sys, 14-65, also see Bad 
Sector File 

Bad Sector File, 14-66 
File Header Block, 14-66 
FileHeaders.Sys, 14-66, also see 
File Header Block 
Master File Directory, 14-66 
Mfd.Sys, 14-66, also see Master 
File Directory 
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System file (cont.) 

Sys(tem) Volume, 14-67 
System Image, 2-2, 2-27 14-67 

cluster workstation, 2-27 , 14-67 
master workstation, 2-27 
standalone workstation, 2-27 
Sys Image . Sys , 14-67 
System Configuration Block, E-12 
Volume Home Block, 14-61 
System Input Manager, 26-3 

CheckpointSysIn service, 26-16 
QueryKbdState service, 26-19 
SetSysInMode service, 26-27 
Sysln, 26-3 

System Manager, Glossary-34 
System partition, 10-2 
System service, 4-11, 13-2 
ConvertToSys service, 13-7 
direct access 

default response exchange, 4-12 
Local Service Code Table, 4-13 
request block, 4-12 
request code, 4-12 
Request primitive, 4-29 
Respond primitive, 4-30 
response exchange , 4-12 
service exchange, 4-12 
Service Exchange Table, 4-13 
Wait primitive, 4-32 
dynamically installed 

extended system partition, 13-2 
operational sequence, 13-3 
restrictions, 13-4 
secondary application 
partition, 13-4 
SetlntHandler service, 29-19 
filter process, 4-15 
request codes, 13-2 
ServRq service, 13-8 
System service access, 4-10 
direct (Request and Wait 
primitives), 4-10 
procedural interface, 4-10 
System service process, 4-10, 13-1 
Sys(tem) Volume, 14-67 
system files, 14-67 
System volume 
! Sys , 14-7 
Sys, 14-6 

Sys(tem) Directory, 14-65 


Task, 7-2 
activating 

LoadTask service, 7-13 
loading, 7-3, 10-6 

LoadTask service, 7-13 
memory allocation, short-lived, 7-3 
primary, 10-6 
secondary, 10-7 

Task image, 2-3, 6-3, 7-2, 7-3 
Task management, 7-1 
Temporary file, 14-7, 14-69 
Terminal emulator, 27-1 
2780/3780, 27-1 
3270, 27-1 
ATE, 27-1 
X . 25 , 27-1 

TerminatePartitionTasks service, 

10-25 

TerminateQueueServer service, 15-13, 
15-34 

Terminating 

application system, 26-13 
ErrorExit procedure, 7-10 
Exit procedure, 7-12 
server process, 15-13 
tasks 

application partition 

VacatePartition service, 10-26 
Text file, Glossary-36 
Timer 

single interval, 28-6 
Timer example program, F-14 
Timer management, 28-1 
Timer Pseudointerrupt Block, 28-8 
ResetTimerlnt primitive, 28-18 
SetTimerlnt primitive, 28-20 
Timer Pseudointerrupt Block format, 
28-9 

Timer Request Block, 28-5 
CloseRTClock service, 28-12 
OpenRTClock service, 28-17 
Timer Request Block format, 28-6 
Time slicing, 3-4 

TPIB, see Timer Pseudointerrupt Block 
Trap Flag, 29-8 
Traps, 29-8 

TRB, see Timer Request Block 
Tree structure 

Volume Home Block, 14-61 
TRUE, Glossary-36 
TruncateDaFile procedure, 19-15 
Type-ahead buffer, 26-7 

FatalError procedure, 30-4 
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Typematic repeating, 26-2 
TypeSector example program, F-4 
Typewriter pad, 26-3 


UCB, see User Control Block 
Underline, 17-13 
Underlining, 23-5, 25-4 
Underscore, see Underlining 
Unencoded keyboard, C-2 
Unencoded mode, 26-1, 26-5 

SetKbdUnencodedMode service, 26-26 
Universal Record Identifier, 16-6 
UnmarkQueueEntry service, 15-35 
URI, see Universal Record Identifier 
User Control Block, 14-70, 14-71 
cluster workstations, 14-71 
GetUCB service, 14-39 
master workstation, 14-71 
local UCBs , 14-71 
remote UCBs, 14-71 
User Control Block format, 14-70 
User number, 14-8, Glossary-37 
GetUserNumber procedure, 3-12 
nnn , 14-69 

Utility, Glossary-37 

VacatePartition service, 10-26 
VAM, see Video Access Method 
Variable-Length Parameter Block, 

9-3 

address, 9-3 

CParams procedure, 9-10 

creating, 9-3 

CSubParams procedure, 9-11 
RgParam procedure, 9-13 
RgParamlnit procedure, 9-14 
RgParamSetEltNext procedure, 9-15 
RgParamSetListStart procedure, 

9-16 

RgParamSetSimple procedure, 9-17 
Variable- length record, 16-1, 18-1 
VCB, see Video Control Block 
VDM, see Video Display Management 
VHB, see Volume Home Block 
Video Access Method, 23-8, 25-1 
Video attributes, 23-4 

basic video capability, 23-6 
character, 23-5, 23-6 
line, 23-4 
screen, 23-4, 23-6 
SetScreenVidAttr service, 24-19 


standard video capability, 23-4 
Video Byte Stream multibyte 
escape sequences, 26-11 
Video capability, 23-3 
advanced, 23-3 
basic, 23-3 

QueryVidHw service, 24-15 
standard, 23-3 
Video Control Block, 23-11 
ResetVideo service, 24-17 
Video Control Block format, 23-12 
Video display 
[Vid] , 17-6 

Video display management, 23-8, 

24-1 

character map, 24-1 
font RAM, 24-1 
frames, 24-1 
memory, 24-1 
screen attributes, 24-1 
video capability, 24-1 
video refresh, 24-1 
Video frame 0, 17-5 
Video management, 23-1 

alphanumeric information, 23-1 
graphic information, 23-1 
Video refresh, 23-5, 23-7 
ResetVideo service, 24-17 
Video software, 23-7 
Video subsystem, 23-1 

ResetVideo service, 24-17 
Video subsystem reinitialization, 

24-2 

Virtual code segment, 8-1, 8-3 
InitOverlays procedure, 8-7 
Virtual code segment management, 8-1, 
8-3 

initializing, 8-3 
linking, 8-3, 8-4 
Virtual memory, 8-2 
VLPB, see Variable-Length Parameter 
Block 

Volname, 14-6, also see Volume name 
Volume, 14-4 

Backup Volume utility, 14-64 
ClearPath service, 14-26 
DismountVolume service, 21-9 
IVolume utility, 14-64 
MountVolume service, 21-15 
password, 14-9 
Restore utility, 14-64 
SetPath service, 14-55 
Volume automatic recognition, 14-6 
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Volume control structures, 14-60 
Allocation Bit Map, 14-60 
directory, 14-65 

extension File Header Block, 14-64 
file, 14-65 

File Header Block, 14-60 
Master File Directory, 14-60 
Volume Home Block, 14-60 
Volume Home Block, 14-60 
Allocation Bit Map, 14-61 
Bad Sector File, 14-61 
Crash Dump Area, 14-61 
directory, 14-61 
File Header Blocks, 14-61 
GetFileStatus service, 14-37 
GetVHB service, 21-13 
Log File, 14-61 
Master File Directory, 14-61 
System Image, 14-61 
Volume Home Block format, 14-63 
Volume name, 14-6, 21-3 
Volume password, 14-9 
Volume space 

allocating, 14-60 
deallocating, 14-60 
location, 14-60 


Wait primitive, 4-22, 4-32 
Waiting state, 3-6 
Word Processor files, 17-25 
Workstation identification 
nnn , 14-68 

Workstation type, 14-67 
WriteAsync procedure, 14-59, 21-29 
Write-behind mode 

Direct Access Method, 19-3 
WriteBsRecord procedure, 17-34 
WriteByte procedure, 17-35 
WriteDaFragment procedure, 19-16 
WriteDaRecord procedure, 19-17 
WriteFile, 14-57, also see Write 
operation 

WriteLog service, 30-5 
Write mode 

OpenRsFile procedure, 18-7 
Write operation, 21-27 
WriteRsRecord procedure, 18-13 
Write service, 14-57 
Write-through mode 

Direct Access Method, 19-3 
Writing to video display (example), 
F-4 


WS>CrashDump.Sys , 14-68 
W Snnn> CrashDump. Sys , 14-68 
W Snnn >SysImage.Sys, 14-67 
wsStatus block format, 11-10 
WS> Sys Image .Sys , 14-67 


X.25 Network Gateway, 17-4, 17-9 
X.25 virtual circuit, 17-4 
[X25] , 17-4 
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